CLGETIMAGEINFO(3clc)

✨ NAME ✨

okay so bestie, welcome to clGetImageInfo 💖 — this is the OpenCL Manual (3clc) page for it, and it does exactly one thing: it gets info that's specific to an image object that you made with clCreateImage. that's it. that's the whole job. 👑

here's the signature, copy it exactly, don't freestyle:

cl_intclGetImageInfo(cl_mem image, cl_image_info param_name,
                     size_t param_value_size, void *param_value,
                     size_t *param_value_size_ret);

like, she's giving "small function, big responsibilities" energy and honestly? iconic. 🫶

---

🌸 PARAMETERS 🌸

okay so this is the part where we meet the whole cast. three of them. all serving very different purposes. let's go. 💅

• image — this is the image object you're interrogating. specify the one you want to ask about. it's the main character of this whole operation. 🔍
• param_name — this tells her what you wanna know. the list of supported param_name types, plus what actually comes back in param_value for clGetImageInfo, is described in the table below. so yeah, the table is the moment. 📋
• param_value — a pointer to memory where the appropriate result you asked for gets returned. and listen: if param_value is NULL, it is ignored. she just... doesn't engage. no cap. 🙈

lowkey important: param_value_size and param_value_size_ret are chillin' right there in the signature, but they don't get their own little bullet in this section. the original keeps them un-listed here, so we're keeping it that way. fr fr. 🧚

more parts coming, don't go anywhere 💜

• param_value_size — this is where you tell the function how many bytes of memory param_value is pointing at. This size must be ≥ the size of the return type as described in the table below. 🫶

okay so here's the tea on what your cl_image_info can be, what type comes back, and what actually lands in param_value:

• CL_IMAGE_FORMAT — return type: cl_image_format. Returns the image format descriptor specified when the image is created with clCreateImage(3clc). ✨
• CL_IMAGE_ELEMENT_SIZE — return type: size_t. Returns the size of each element of the image memory object given by image. An element is made up of n channels. The value of n is given in the cl_image_format descriptor. 💅
• CL_IMAGE_ROW_PITCH — return type: size_t. Returns the size in bytes of a row of elements of the image object given by image. 🌸
• CL_IMAGE_SLICE_PITCH — return type: size_t. Returns the calculated slice pitch in bytes of a 2D slice for the 3D image object or the size of each image in a 1D or 2D image array given by image. For a 1D image, 1D image buffer and 2D image object return 0. 🦋
• CL_IMAGE_WIDTH — return type: size_t. Returns the width of the image in pixels. 👑
• CL_IMAGE_HEIGHT — return type: size_t. Returns the height of the image in pixels. For a 1D image, 1D image buffer and 1D image array object, height = 0. 💀
• CL_IMAGE_DEPTH — return type: size_t. Returns the depth of the image in pixels. For a 1D image, 1D image buffer, 2D image or 1D and 2D image array object, depth = 0. 🌈
• CL_IMAGE_ARRAY_SIZE — return type: size_t. Returns the number of images in the image array. If image is not an image array, 0 is returned. 🎀
• CL_IMAGE_BUFFER — return type: cl_mem. Returns the buffer object associated with image. 🍓
• CL_IMAGE_NUM_MIP_LEVELS — return type: cl_uint. Returns num_mip_levels associated with image. 🧚
• CL_IMAGE_NUM_SAMPLES — return type: cl_uint. Returns num_samples associated with image. 💜
• CL_IMAGE_D3D10_SUBRESOURCE_KHR — return type: ID3D10Resource *. (if the cl_khr_d3d10_sharing(3clc) extension is enabled) If image was created using clCreateFromD3D10Texture2DKHR(3clc) or clCreateFromD3D10Texture3DKHR(3clc), returns the
• CL_IMAGE_DX9_MEDIA_PLANE_KHR — type cl_uint. It hands you back the plane argument value that was set when memobj got created with clCreateFromDX9MediaSurfaceKHR(3clc). 💅 (only a thing if the cl_khr_dx9_media_sharing(3clc) extension is supported, okurrr)
• CL_IMAGE_DX9_MEDIA_SURFACE_PLANE_KHR — also cl_uint, and yes it's the same energy: returns the plane argument value that was specified when memobj was created using clCreateFromDX9MediaSurfaceKHR(3clc). ✨ (again, only if the cl_khr_dx9_media_sharing(3clc) extension is supported)
• CL_IMAGE_D3D11_SUBRESOURCE_KHR — type ID3D11Resource *. If the cl_khr_d3d11_sharing(3clc) extension is supported, and if the image was created using clCreateFromD3D11Texture2DKHR(3clc) or clCreateFromD3D11Texture3DKHR(3clc), it returns the subresource argument that was specified when the image was created. 🦋

---

param_value_size_ret — this one returns the actual size in bytes of the data you're querying through param_value. And if param_value_size_ret is NULL? Bestie, it's simply ignored. 🙈

💭 NOTES

To get info that's common to all memory objects — so both buffer objects and image objects, the whole family — use the clGetMemObjectInfo(3clc) function instead. iykyk 💖

🚨 ERRORS

Returns CL_SUCCESS when everything goes right. Otherwise, it throws one of these at you:

• CL_INVALID_VALUE — if param_name is not valid, or if the size in bytes specified by param_value_size is < the size of the return type as described in the table above and param_value is not NULL.
• CL_INVALID_MEM_OBJECT — if image is a not a valid image object. 😭
• 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. 💀
• CL_INVALID_DX9_MEDIA_SURFACE_KHR — if param_name is CL_IMAGE_DX9_MEDIA_PLANE_KHR and image was not created by the function clCreateFromDX9MediaSurfaceKHR(3clc). (If the cl_khr_dx9_media_sharing(3clc) extension is supported)
• CL_INVALID_D3D10_RESOURCE_KHR — if param_name is CL_MEM_D3D10_SUBRESOURCE_KHR and image was not created by the function clCreateFromD3D10Texture2DKHR(3clc) or clCreateFromD3D10Texture3DKHR(3clc). (If the cl_khr_d3d10_sharing(3clc) extension is supported)
• CL_INVALID_D3D11_RESOURCE_KHR — if param_name is CL_MEM_D3D11_SUBRESOURCE_KHR and image was not created by the function clCreateFromD3D11Texture2DKHR(3clc) or clCreateFromD3D11Texture3DKHR(3clc). (If the cl_khr_d3d11_sharing(3clc) extension is supported)

no cap, if you're getting one of those last three, it's almost always a "wrong function made this image" situation, not a you problem. 👑

📜 SPECIFICATION

OpenCL Specification[1]

👀 SEE ALSO

clGetMemObjectInfo(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 116, section 5.3.6 - Image Object Queries.

---

and that's the whole page bestie, we ate and left zero crumbs 🍓 This lil icon dropped on 01/14/2021, it's the baby of The Khronos Group, and its whole official name is CLGETIMAGEINFO(3clc). go query those images, main character 💅✨