IMAGEDESCRIPTOR(3clc)

💖 IMAGEDESCRIPTOR 💖 — the imageDescriptor manual page from the OpenCL manual (3clc)

okay bestie, sit down, hydrate, because we're about to get into imageDescriptor and it's lowkey the blueprint for every image you'll ever make in OpenCL 🎀

---

✨ NAME ✨

imageDescriptor — the image descriptor structure. It's the lil form you fill out that says what kind of image (or image array) you're making and how big it is. It's defined as:

typedef struct _cl_image_desc {
cl_mem_object_type image_type; size_t
image_width; size_t image_height;
size_t image_depth; size_t
image_array_size; size_t
image_row_pitch; size_t
image_slice_pitch; cl_uint
num_mip_levels; cl_uint num_samples;
cl_mem buffer; } cl_image_desc;

the way that struct is formatted... iconic honestly 💅

---

🦋 MEMBERS 🦋

• image_type — tells the world what kind of image this is. It must be one of CL_MEM_OBJECT_IMAGE1D, CL_MEM_OBJECT_IMAGE1D_BUFFER, CL_MEM_OBJECT_IMAGE1D_ARRAY, CL_MEM_OBJECT_IMAGE2D, CL_MEM_OBJECT_IMAGE2D_ARRAY, or CL_MEM_OBJECT_IMAGE3D. no other options, we don't do that here 🙅‍♀️
• image_width — how wide the image is, in pixels. the rules go like this:
  • for a 2D image and image array, image_width must be ≤ CL_DEVICE_IMAGE2D_MAX_WIDTH.
  • for a 3D image, image_width must be ≤ CL_DEVICE_IMAGE3D_MAX_WIDTH.
  • for a 1D image buffer, image_width must be ≤ CL_DEVICE_IMAGE_MAX_BUFFER_SIZE.
  • for a 1D image and 1D image array, image_width must be ≤ CL_DEVICE_IMAGE2D_MAX_WIDTH.
• image_height — how tall the image is, in pixels. this one only shows up if your image is a 2D, 3D or 2D image array. limits:
  • for a 2D image or image array, image_height must be ≤ CL_DEVICE_IMAGE2D_MAX_HEIGHT.
  • for a 3D image, image_height must be ≤ CL_DEVICE_IMAGE3D_MAX_HEIGHT.
• image_depth — how deep the image is, in pixels. only used if it's a 3D image, and it must be a value ≥ 1 and ≤ CL_DEVICE_IMAGE3D_MAX_DEPTH. periodt.
• image_array_size — how many images live in the image array. only used if it's a 1D or 2D image array. if you specify it, it must be a value ≥ 1 and ≤ CL_DEVICE_IMAGE_MAX_ARRAY_SIZE.

heads up bestie 📢 reading and writing 2D image arrays from a kernel with image_array_size = 1 may be lower performance than 2D images. like, the vibes are worse. just so you know.

• image_row_pitch — the scan-line pitch, in bytes. okay so:
  • this must be 0 if host_ptr is NULL.
  • it can be either 0 or ≥ image_width * size of element in bytes if host_ptr is not NULL.
  • if host_ptr is not NULL and image_row_pitch = 0, then image_row_pitch is calculated as image_width * size of element in bytes.
  • if image_row_pitch is not 0, it must be a multiple of the image element size in bytes.
• image_slice_pitch — the size in bytes of each 2D slice in the 3D image, or the size in bytes of each image in a 1D or 2D image array. the tea ☕:
  • this must be 0 if host_ptr is NULL.
  • if host_ptr is not NULL, image_slice_pitch can be either 0 or ≥ image_row_pitch * image_height for a 2D image array or 3D image, and can be either 0 or ≥ image_row_pitch for a 1D image array.
  • if host_ptr is not NULL and image_slice_pitch = 0, then image_slice_pitch is calculated as image_row_pitch * image_height for a 2D image array or 3D image, and as image_row_pitch for a 1D image array.
  • if image_slice_pitch is not 0, it must be a multiple of the image_row_pitch.
• num_mip_level, num_samples — , must be 0. (yes that's the whole thing. they must be 0. no notes 💀)
• buffer — refers to a valid buffer memory object if image_type is CL_MEM_OBJECT_IMAGE1D_BUFFER. otherwise it must be NULL. for a 1D image buffer object, the image pixels are taken from the buffer object's data store. when the contents of a buffer object's data store are modified, those changes are reflected in the contents of the 1D image buffer object and vice-versa at corresponding sychronization points. also: image_width * size of element in bytes must be ≤ size of buffer object data store.

---

⚠️ NOTE ⚠️

Concurrent reading from, writing to and copying between both a buffer object and 1D image buffer object associated with the buffer object is undefined. that's the danger zone, don't do it 🚨 Only reading from both a buffer object and 1D image buffer object associated with the buffer object is defined.

---

📜 SPECIFICATION 📜

OpenCL Specification[1]

---

👀 SEE ALSO 👀

• cl_image_format(3clc)

---

👑 AUTHORS 👑

The Khronos Group

---

💜 COPYRIGHT 💜

Copyright © 2007-2010 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 95, section 5.3.1.2 - Image Descriptor

---

and that's the whole page bestie!! 🫶 brought to you by The Khronos Group, dated 01/14/2021, from the IMAGEDESCRIPTOR(3clc) era of the OpenCL manual — stay hydrated, check your image_row_pitch multiples, and slay ✨💖