IMAGEFUNCTIONS(3clc)

📦
version 1.0~svn33624 · 3 versions
, in ubuntu jammy, ubuntu noble

okay so this is IMAGE READ, WRITE, A, page 3 of the OpenCL Manual (you'll see it written as 3clc). It's the glow-up index page for the image read/write/query built-ins — every single one of them, and clicking any item in the original table takes you to that function's own page. Bestie, consider this your map. 🗺️✨

✨ NAME ✨

Image_Read_and_Write_Functions — built-in functions to read, write, and query image memory objects. Tap any item below and it'll spill the details on that function. 🫶

🌸 the whole roster 🌸

💅 1D girlies

  • read_imagef1d(3clc) for 1D — do an element lookup in the 1D image object, with or without a sampler, and get back floating-point values. 💖
  • read_imagei1d(3clc) for 1D — do an element lookup in the 1D image object, with or without a sampler, and get back unnormalized signed integer and unsigned integer values. 🔢
  • read_imageh1d(3clc) for 1D — OPTIONAL function that does an element lookup in the 1D image object, with or without a sampler, returning floating-point values. It's enabled with cl_khr_fp16(3clc). ✨
  • write_image1d(3clc) for 1D — write a color value to a location in the 2D image object. The half type is enabled with cl_khr_fp16(3clc). 🖊️

🦋 2D besties

  • read_imagef2d(3clc) for 2D — do an element lookup in the 2D image object, with or without a sampler, and get back floating-point values. 💖
  • read_imagei2d(3clc) for 2D — do an element lookup in the 2D image object, with or without a sampler, and get back unnormalized signed integer and unsigned integer values. 🔢
  • read_imageh2d(3clc) for 2D — OPTIONAL function that does an element lookup in the 2D image object, with or without a sampler, returning floating-point values. It's enabled with cl_khr_fp16(3clc). ✨
  • write_image2d(3clc) for 2D — write a color value to a location in the 2D image object. The half type is enabled with cl_khr_fp16(3clc). 🖊️

🧚 3D main characters

  • read_imagef3d(3clc) for 3D — do an element lookup in the 3D image object, with or without a sampler, and get back floating-point values. 💖
  • read_imagei3d(3clc) for 3D — do an element lookup in the 3D image object, with or without a sampler, and get back unnormalized signed integer and unsigned integer values. 🔢
  • read_imageh3d(3clc) for 3D — OPTIONAL function that does an element lookup in the 3D image object, with or without a sampler, returning floating-point values. It's enabled with cl_khr_fp16(3clc). ✨
  • write_image3d(3clc) for 3D — write a color value to a location in the 2D image object. The half type is enabled with cl_khr_fp16(3clc). 🖊️

👑 the little getters that could (query squad)

fr fr, that's the entire table, no skips, no cuts. 💖

📝 NOTES 💭

okay bestie, listen up, because this is the part where it gets specific. The built-in functions defined in this section can only be used with image memory objects. And an image memory object? It gets accessed by specific function calls that read from and/or write to specific locations in the image. That's the whole vibe. 🖼️✨

Image memory objects that are being read by a kernel should be declared with the accessQualifiers(3clc) qualifier. And if you go and do write_image calls on image memory objects declared with the accessQualifiers(3clc) qualifier? 💀 Compilation error. Straight up. No warning, no mercy.

Image memory objects that are being written to by a kernel should be declared with the accessQualifiers(3clc) qualifier. And flip it: read_image calls to image memory objects declared with the accessQualifiers(3clc) qualifier will generate a compilation error too. 😭

🚨 and bestie, hear me on this one: read_image and write_image calls to the same image memory object in a kernel are not supported. Not "discouraged". Not "a little sketchy". Not supported. periodt.

The read_image calls return a four component floating-point, integer or unsigned integer color value. Those color values are identified as x, y, z, w where:

  • x — the red component 🍓
  • y — the green component 🌿
  • z — the blue component 🦋
  • w — the alpha component 💜

like, the alphabet soup is just RGBA wearing a lil disguise. iykyk. 👑

📜 SPECIFICATION 📜

OpenCL Specification[1]

👀 SEE ALSO 👀

go read those too, they're part of the lore 🫶

✍️ AUTHORS ✍️

The Khronos Group

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 condition:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Materials.

📎 NOTES (yes, again — these are the footnote ones) 📎

  1. OpenCL Specification — page 292, section 6.12.14 - Image Read and Write Functions

and that's a wrap, bestie 💖 this page is brought to you by The Khronos Group, dated 01/14/2021, filed under IMAGE READ, WRITE, A(3clc) — go forth and slay your image reads, but for real, do not read and write the same image object in one kernel, i love u, bye 🎀✨

📦 where this page comes from