OpenCL™规范 5.5.3. 取消映射的内存对象

5.5.3. Unmapping Mapped Memory Objects

5.5.3. 取消映射映射的内存对象

To enqueue a command to unmap a previously mapped region of a memory object, call the function

要将取消映射内存对象的先前映射区域的命令排入队列，请调用函数

// Provided by CL_VERSION_1_0
cl_int clEnqueueUnmapMemObject(
    cl_command_queue command_queue,
    cl_mem memobj,
    void* mapped_ptr,
    cl_uint num_events_in_wait_list,
    const cl_event* event_wait_list,
    cl_event* event);

• command_queue must be a valid host command-queue.

• command_queue必须是有效的主机命令队列。

• memobj is a valid memory (buffer or image) object. The OpenCL context associated with command_queue and memobj must be the same.

• memobj是一个有效的内存（缓冲区或图像）对象。与command_queue和memobj关联的OpenCL上下文必须相同。

• mapped_ptr is the host address returned by a previous call to clEnqueueMapBuffer, or clEnqueueMapImage for memobj.

• ​mapped_ptr是上一次调用clEnqueueMapBuffer返回的主机地址，对于memobj，则为clEnqueueMappingImage。

• event_wait_list and num_events_in_wait_list specify events that need to complete before clEnqueueUnmapMemObject can be executed. If event_wait_list is NULL, then clEnqueueUnmapMemObject does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same. The memory associated with event_wait_list can be reused or freed after the function returns.

• ​event_wait_list和num_events_in_wait_list指定在执行clEnqueueUnmapMemObject之前需要完成的事件。如果event_wait_list为NULL，则clEnqueueUnmapMemObject不等待任何事件完成。如果event_wait_list为NULL，则num_events_in_wait_list必须为0。如果event_wait_list不为NULL，则event_wail_list指向的事件列表必须有效，并且num_events_in_wait_list必须大于0。event_wait_list中指定的事件充当同步点。与event_wait_list和command_queue中的事件关联的上下文必须相同。函数返回后，可以重用或释放与event_wait_list关联的内存。

• event returns an event object that identifies this command and can be used to query or queue a wait for this command to complete. If event is NULL or the enqueue is unsuccessful, no event will be created and therefore it will not be possible to query the status of this command or to wait for this command to complete. If event_wait_list and event are not NULL, event must not refer to an element of the event_wait_list array.

• event返回一个标识此命令的事件对象，可用于查询或排队等待此命令完成。如果事件为NULL或排队不成功，则不会创建任何事件，因此无法查询此命令的状态或等待此命令完成。如果event_wait_list和event不为NULL，则event不能引用event_wail_list数组的元素。

Reads or writes from the host using the pointer returned by clEnqueueMapBuffer or clEnqueueMapImage are considered to be complete.

​使用clEnqueueMapBuffer或clEnqueueMap Image返回的指针从主机读取或写入被视为完成。

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

clEnqueueMapBuffer和clEnqueueMappingImage递增内存对象的映射计数。内存对象的初始映射计数值为零。对同一内存对象多次调用clEnqueueMapBuffer或clEnqueueMap Image将使此映射计数增加相应的调用数。clEnqueueUnmapMemObject递减内存对象的映射计数。

clEnqueueMapBuffer, and clEnqueueMapImage act as synchronization points for a region of the buffer object being mapped.

clEnqueueMapBuffer和clEnqueueMapImage充当被映射的缓冲区对象的区域的同步点。

clEnqueueUnmapMemObject returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

如果函数执行成功，clEnqueueUnmapMemObject将返回CL_SUCCESS。否则，它将返回以下错误之一：

• CL_INVALID_COMMAND_QUEUE if command_queue is not a valid host command-queue.

• CL_INVALID_COMMAND_QUEUE（如果command_queue不是有效的主机命令队列）。

• CL_INVALID_MEM_OBJECT if memobj is not a valid memory object or is a pipe object.

• 如果memobj不是有效的内存对象或是管道对象，则CL_INVALID_MEM_OBJECT。

• CL_INVALID_VALUE if mapped_ptr is not a valid pointer returned by clEnqueueMapBuffer or clEnqueueMapImage for memobj.

• CL_INVALID_VALUE，如果mapped_ptr不是clEnqueueMapBuffer或clEnqueueMap Image为memobj返回的有效指针。

• CL_INVALID_EVENT_WAIT_LIST if event_wait_list is NULL and num_events_in_wait_list > 0, or if 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_EVENT_WAIT_LIST如果event_wait_list为NULL且num_events_in_wait_list>0，或者如果event_wait_list不为NULL且num_events_in_wait_list为0，或者如果event_wait_list中的事件对象不是有效事件。

• CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.

• CL_OUT_OF_RESOURCES，如果在设备上分配OpenCL实现所需的资源失败。

• CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

• CL_OUT_OF_HOST_MEMORY，如果在主机上分配OpenCL实现所需的资源失败。

• CL_INVALID_CONTEXT if context associated with command_queue and memobj are not the same or if the context associated with command_queue and events in event_wait_list are not the same.

• CL_INVALID_CONTEXT如果与command_queue和memobj关联的上下文不相同，或者与command_ queue关联的上下文和event_wait_list中的事件不相同。