CLENQUEUEMAPIMAGE(3clc)

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

okay so bestie, you're looking at the CLENQUEUEMAPIMAGE(3clc) manual page — part 1 of 2, so don't go anywhere 💖

✨ NAME ✨

clEnqueueMapImage — Enqueues a command to map a region of an image object into the host address space and returns a pointer to this mapped region.

here's the exact signature, no cap:

void * clEnqueueMapImage(cl_command_queue command_queue, cl_mem image,
                         cl_bool blocking_map, cl_map_flags map_flags,
                         const size_t * origin, const size_t * region,
                         size_t *image_row_pitch,
                         size_t *image_slice_pitch,
                         cl_uint num_events_in_wait_list,
                         const cl_event *event_wait_list,
                         cl_event *event, cl_int *errcode_ret);

✨ PARAMETERS ✨

  • command_queue — bestie, this has to be a valid command-queue, no exceptions. 💅
  • image — a valid image object, and the OpenCL context linked to both command_queue and image must be the same. 🖼️
  • blocking_map — tells you if the map operation is blocking or non-blocking. 🚦
    • if it's CL_TRUE, clEnqueueMapImage does not return until that region in image is mapped into host address space, and then you can access it with the returned pointer.
    • if it's CL_FALSE (non-blocking), the returned pointer can't be used until the map command finishes. The event argument gives you an event object to query the map command's status. Once it's done, you can access the mapped region with the pointer.
  • map_flags — a bit-field with these supported values: 🔥
    • CL_MAP_READ — maps the region for reading. The pointer from clEnqueueMapBuffer(3clc) or clEnqueueMapImage is guaranteed to have the latest bits when the command completes.
    • CL_MAP_WRITE — maps the region for writing. Same guarantee about latest bits when the command completes.
    • CL_MAP_WRITE_INVALIDATE_REGION — maps the region for writing, but the contents are discarded. Usually when the host overwrites the region. This lets the implementation skip guaranteeing latest bits, which can be a huge performance boost. Note: CL_MAP_READ or CL_MAP_WRITE and CL_MAP_WRITE_INVALIDATE_REGION are mutually exclusive. 🚫
  • origin — defines the offset. For 1D/2D/3D images it's (x, y, z) in pixels; for 2D image array it's (x, y) offset and image index; for 1D image array it's (x) offset and image index. If image is 2D, origin[2] must be 0. If 1D image or 1D image buffer, origin[1] and origin[2] must be 0. If 1D image array, origin[2] must be 0, and origin[1] describes the image index. If 2D image array, origin[2] describes the image index. 📍
  • region — defines the size. For 1D/2D/3D rectangle it's (width, height, depth) in pixels; for 2D rectangle it's (width, height) and number of images in 2D image array; for 1D rectangle it's (width) and number of images in 1D image array. If 2D image, region[2] must be 1. If 1D image or 1D image buffer, region[1] and region[2] must be 1. If 1D image array, region[2] must be 1. 📐
  • image_row_pitch — returns the scan-line pitch in bytes for the mapped region. Must be non-NULL. 📏
  • image_slice_pitch — returns the size in bytes of each 2D slice of a 3D image, or the size of each 1D or 2D image in a 1D or 2D image array, for the mapped region. For 1D and 2D images, zero is returned if this argument isn't NULL. For 3D image, 1D, and 2D image array, it must be non-NULL. 🍰
  • event_wait_list, num_events_in_wait_list — these specify events that must complete before clEnqueueMapImage runs. If event_wait_list is NULL, then no events are waited on, and num_events_in_wait_list must be 0. If it's not NULL, the list must be valid and num_events_in_wait_list must be > 0. The events act as synchronization points. The context of the events and command_queue must match. You can reuse or free the memory for event_wait_list after the function returns. ⏳
  • event — returns an event object that identifies this specific copy command, so you can query or queue a wait for it. event can be NULL, but then you can't query status or wait on it. If both event_wait_list and event are not NULL, event should not be an element of event_wait_list. 🎫
  • errcode_ret — returns an appropriate error code. If it's NULL, no error code comes back. ⚠️

part 2 loading... 🦋

📝 NOTES 📝

okay bestie, listen up, this part is lowkey the most important vibe check of the whole page 🫶

So the pointer you get back maps a 1D, 2D or 3D region starting at origin, and here's how big it is (and it's at least this big, no cap):

  • For a 1D image, 1D image buffer or 1D image array: region[0] pixels in size ✨
  • For a 2D image or 2D image array: (image_row_pitch * region[1]) pixels in size 💅
  • For a 3D image: (image_slice_pitch * region[2]) pixels in size 🌈
🚨 and if you go touching memory outside that region? the result is undefined. literally do not. that's the void, bestie, we don't go there 💀

Now, if the image object was created with CL_MEM_USE_HOST_PTR set in mem_flags, then the following is true (this is the good stuff, iykyk):

  • The host_ptr you specified in clCreateImage(3clc) is guaranteed to contain the latest bits in the region being mapped once the clEnqueueMapImage command has completed 👑
  • The pointer value returned by clEnqueueMapImage will be derived from the host_ptr you specified when the image object was created 🎀

Mapped image objects get unmapped using clEnqueueUnmapMemObject(3clc) — that's the exit door, don't forget to use it.

Okay now, the mapped count lore, because this is where people get caught slipping 🙈

clEnqueueMapBuffer(3clc) and clEnqueueMapImage increment the mapped count of the memory object. The initial mapped count value of a memory object is zero. Multiple calls to clEnqueueMapBuffer(3clc) or clEnqueueMapImage on the same memory object will increment this mapped count by the appropriate number of calls. And clEnqueueUnmapMemObject decrements the mapped count of the memory object.

So like… it's a counter. Count your maps, count your unmaps. Balance. ✨

Also! clEnqueueMapBuffer(3clc) and clEnqueueMapImage act as synchronization points for a region of the buffer object being mapped.

🚨 ERRORS 🚨

clEnqueueMapImage will return a pointer to the mapped region if the function is executed successfully — and errcode_ret is set to CL_SUCCESS. slay 💅

Otherwise? You get a NULL pointer returned, with one of the following error values dropped into errcode_ret:

  • CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
  • CL_INVALID_CONTEXT if the context associated with command_queue and image are not the same, or if the context associated with command_queue and events in event_wait_list are not the same.
  • CL_INVALID_MEM_OBJECT if image is not a valid image object.
  • CL_INVALID_VALUE if the region being mapped given by (origin, origin+region) is out of bounds, or if values specified in map_flags are not valid.
  • CL_INVALID_VALUE if values in origin and region do not follow the rules described in the argument description for origin and region.
  • CL_INVALID_VALUE if image_row_pitch is NULL.
  • CL_INVALID_VALUE if image is a 3D image, 1D or 2D image array object and image_slice_pitch is NULL.
  • CL_INVALID_EVENT_WAIT_LIST if event_wait_list is NULL and num_events_in_wait_list > 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.
  • CL_INVALID_IMAGE_SIZE if image dimensions (image width, height, specified or compute row and/or slice pitch) for image are not supported by the device associated with queue.
  • CL_INVALID_IMAGE_FORMAT if image format (image channel order and data type) for image are not supported by the device associated with queue.
  • CL_MAP_FAILURE if there is a failure to map the requested region into the host address space. This error cannot occur for image objects created with CL_MEM_USE_HOST_PTR or CL_MEM_ALLOC_HOST_PTR.
  • CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the map operation is blocking and the execution status of any of the events in event_wait_list is a negative integer value.
  • CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with buffer.
  • CL_INVALID_OPERATION if the device associated with command_queue does not support images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the table of OpenCL Device Queries for clGetDeviceInfo(3clc) is CL_FALSE.
  • CL_INVALID_OPERATION if image has been created with CL_MEM_HOST_WRITE_ONLY or CL_MEM_HOST_NO_ACCESS and CL_MAP_READ is set in map_flags, or if image has been created with CL_MEM_HOST_READ_ONLY or CL_MEM_HOST_NO_ACCESS and CL_MAP_WRITE or CL_MAP_WRITE_INVALIDATE_REGION is set in map_flags.
  • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
  • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
🫶 read those twice, bestie. every single one of them is a real thing that can happen to you.

📚 SPECIFICATION 📚

OpenCL Specification[1]

👀 SEE ALSO 👀

clEnqueueMapBuffer(3clc), clEnqueueUnmapMemObject(3clc)

🖋️ 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 conditions:

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

(yes bestie, we keep the whole license. it's legally iconic. do not touch a single character. 💖)

🔖 NOTES (the reference one) 🔖

  1. OpenCL Specification page 112, section 5.3.5 - Mapping Image Objects

and that's a wrap on CLENQUEUEMAPIMAGE(3clc) 🎀 go forth and map responsibly, bestie, and always unmap 💜

The Khronos Group blessed us with this one on 01/14/2021 — that's the source, that's the version, and she's iconic for it. 🦋✨

📦 where this page comes from