Enqueues a command to map a region of the buffer object given by buffer
into the host address space and returns a pointer to this mapped region.
command_queue
Must be a valid command-queue.
blocking_map
Indicates if the map operation is blocking
or
non-blocking
.
If blocking_map
is CL_TRUE
,
clEnqueueMapBuffer
does not return until the specified
region in buffer
is mapped into the host address space
and the application can access the contents of the mapped region using
the pointer returned by clEnqueueMapBuffer
.
If blocking_map
is CL_FALSE
i.e. map operation is non-blocking, the pointer to the mapped region
returned by clEnqueueMapBuffer
cannot be used until
the map command has completed. The event
argument
returns an event object which can be used to query the execution status
of the map command. When the map command is completed, the application
can access the contents of the mapped region using the pointer returned
by clEnqueueMapBuffer
.
map_flags
A bit-bield with the following supported values.
cl_map_flags | Description |
---|---|
CL_MAP_READ
|
This flag specifies that the region being mapped in the memory object is being mapped for reading.
The pointer returned by |
CL_MAP_WRITE
|
This flag specifies that the region being mapped in the memory object is being mapped for writing.
The pointer returned by |
CL_MAP_WRITE_INVALIDATE_REGION
|
This flag specifies that the region being mapped in the memory object is being mapped for writing.
The contents of the region being mapped are to be discarded.
This is typically the case
when the region being mapped is overwritten by the host. This
flag allows the implementation
to no longer guarantee that the pointer returned by
|
buffer
A valid buffer object. The OpenCL context associated with command_queue
and buffer
must be the same.
offset,
size
The offset in bytes and the size of the region in the buffer object that is being mapped.
event_wait_list,
num_events_in_wait_list
Specify events that need to complete before this particular
command can be executed. If event_wait_list
is NULL, then this particular command 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
Returns an event object that identifies this particular copy command
and can be used to query or queue a wait for this particular command
to complete. event
can be NULL in which case
it will not be possible for the application to query the status of
this command or queue a wait for this command to complete. If the
event_wait_list
and the event
arguments are not NULL, the event
argument should not
refer to an element of the event_wait_list
array.
errcode_ret
Returns an appropriate error code. If errcode_ret
is NULL, no error code is returned.
The returned pointer maps a region starting at offset
and is at
least size
bytes in size. The result of a memory access outside
this region is undefined.
If the buffer object is created with CL_MEM_USE_HOST_PTR
set in
mem_flags
, the following will be true:
host_ptr
specified in
clCreateBuffer
is guaranteed to contain the latest bits in the region being mapped when the
clEnqueueMapBuffer
command has completed.
clEnqueueMapBuffer
will be derived
from the host_ptr
specified when the buffer object is created.
Mapped buffer objects are unmapped using clEnqueueUnmapMemObject.
clEnqueueMapBuffer
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
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
and clEnqueueMapImage
act as synchronization points for a region of the buffer object being mapped.
clEnqueueMapBuffer
will return a pointer to the mapped region
if the function is executed successfully. The errcode_ret
is set
to CL_SUCCESS.
A NULL pointer is returned otherwise with one of the following error values returned
in errcode_ret
:
command_queue
is not a valid command-queue.
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.
image
is not a valid image object.
offset
, size
)
is out of bounds or if size
is 0 or values specified in
map_flags
are not valid.
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.
buffer
is a sub-buffer object and offset
specified when the sub-buffer object is created is not aligned to
CL_DEVICE_MEM_BASE_ADDR_ALIGN
value for device associated
with queue
.
CL_MEM_USE_HOST_PTR
or
CL_MEM_ALLOC_HOST_PTR
.
event_wait_list
is a negative integer value.
buffer
.
buffer
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 buffer
has been created with CL_MEM_HOST_READ_ONL
or
CL_MEM_HOST_NO_ACCESS
and CL_MAP_WRITE
or CL_MAP_WRITE_INVALIDATE_REGION
is set in
map_flags
.