CLCREATESAMPLER(3clc)

👑 CLCREATESAMPLER — okay bestie, let's build a sampler 💖

Welcome to the OpenCL Manual, section 3clc — this is the page for clCreateSampler, and yes it's giving very much "image-reading era" ✨

---

🌸 NAME 🌸

clCreateSampler — literally just creates a sampler object, no cap 🫶

cl_sampler clCreateSampler(cl_context context,
                           cl_bool normalized_coords,
                           cl_addressing_mode addressing_mode,
                           cl_filter_mode filter_mode,
                           cl_int *errcode_ret);

---

🎀 PARAMETERS 🎀

• context — has to be a valid OpenCL context, periodt. No fake contexts allowed 💅
• normalized_coords — decides whether the image coords you're giving are normalized or not. If it's CL_TRUE, yep they're normalized; if it's CL_FALSE, nope they're not 🙈
• addressing_mode — tells you how out-of-range image coordinates get handled when you're reading from an image. You can set it to CL_ADDRESS_MIRRORED_REPEAT, CL_ADDRESS_REPEAT, CL_ADDRESS_CLAMP_TO_EDGE, CL_ADDRESS_CLAMP, or CL_ADDRESS_NONE ⭐
• filter_mode — the type of filter that must be applied when reading an image. This one can be CL_FILTER_NEAREST or CL_FILTER_LINEAR 🌈
• errcode_ret — returns an appropriate error code. If errcode_ret is NULL, then no error code gets returned. That's it, that's the deal 🤷

---

🦋 NOTES 🦋

A sampler object is basically the vibe guide for how to sample an image when that image gets read in the kernel, bestie. The built-in functions that read from an image inside a kernel take a sampler as an argument. And those sampler arguments to the image read function? They can be sampler objects you made with OpenCL functions and passed as argument values to the kernel — OR they can be samplers declared inside a kernel. This section is all about the first way: making sampler objects with OpenCL functions 💖

If you wanna know more about working with samplers, go check out sampler_t(3clc) — it's linked down below, iykyk 👑

---

💀 ERRORS 💀

So here's the tea: you get a valid non-zero sampler object back and errcode_ret is set to CL_SUCCESS if the sampler object got created successfully. Otherwise? You get a NULL value, and one of these error values lands in errcode_ret:

• CL_INVALID_CONTEXT — if context is not a valid context 😭
• CL_INVALID_VALUE — if addressing_mode, filter_mode, or normalized_coords, or some combination of these argument values, are not valid 🚩
• CL_INVALID_OPERATION — if images are not supported by any device associated with context (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the table of OpenCL Device Queries for clGetDeviceInfo(3clc) is CL_FALSE) 💀
• CL_OUT_OF_RESOURCES — if there's a failure to allocate resources required by the OpenCL implementation on the device 😮💨
• CL_OUT_OF_HOST_MEMORY — if there's a failure to allocate resources required by the OpenCL implementation on the host 🫠

---

⭐ SPECIFICATION ⭐

OpenCL Specification[1]

---

🌈 SEE ALSO 🌈

clRetainSampler(3clc), clReleaseSampler(3clc), clGetSamplerInfo(3clc), classDiagram(3clc) sampler_t(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 🧚

1. OpenCL Specification — page 128, section 5.5.1 - Creating Sampler Objects 📖

---

That's the whole page, bestie — go forth and sample some images 💅✨

Brought to you by The Khronos Group, dated 01/14/2021, from the CLCREATESAMPLER(3clc) page of the OpenCL Manual. 🫶🌸