Safe Haskell | Safe-Infered |
---|
- type CLCommandQueue = Ptr ()
- data CLCommandQueueProperty
- data CLMapFlag
- clCreateCommandQueue :: CLContext -> CLDeviceID -> [CLCommandQueueProperty] -> IO CLCommandQueue
- clRetainCommandQueue :: CLCommandQueue -> IO Bool
- clReleaseCommandQueue :: CLCommandQueue -> IO Bool
- clGetCommandQueueContext :: CLCommandQueue -> IO CLContext
- clGetCommandQueueDevice :: CLCommandQueue -> IO CLDeviceID
- clGetCommandQueueReferenceCount :: CLCommandQueue -> IO CLuint
- clGetCommandQueueProperties :: CLCommandQueue -> IO [CLCommandQueueProperty]
- clSetCommandQueueProperty :: CLCommandQueue -> [CLCommandQueueProperty] -> Bool -> IO [CLCommandQueueProperty]
- clEnqueueReadBuffer :: Integral a => CLCommandQueue -> CLMem -> Bool -> a -> a -> Ptr () -> [CLEvent] -> IO CLEvent
- clEnqueueWriteBuffer :: Integral a => CLCommandQueue -> CLMem -> Bool -> a -> a -> Ptr () -> [CLEvent] -> IO CLEvent
- clEnqueueReadImage :: Integral a => CLCommandQueue -> CLMem -> Bool -> (a, a, a) -> (a, a, a) -> a -> a -> Ptr () -> [CLEvent] -> IO CLEvent
- clEnqueueWriteImage :: Integral a => CLCommandQueue -> CLMem -> Bool -> (a, a, a) -> (a, a, a) -> a -> a -> Ptr () -> [CLEvent] -> IO CLEvent
- clEnqueueCopyImage :: Integral a => CLCommandQueue -> CLMem -> CLMem -> (a, a, a) -> (a, a, a) -> (a, a, a) -> [CLEvent] -> IO CLEvent
- clEnqueueCopyImageToBuffer :: Integral a => CLCommandQueue -> CLMem -> CLMem -> (a, a, a) -> (a, a, a) -> a -> [CLEvent] -> IO CLEvent
- clEnqueueCopyBufferToImage :: Integral a => CLCommandQueue -> CLMem -> CLMem -> a -> (a, a, a) -> (a, a, a) -> [CLEvent] -> IO CLEvent
- clEnqueueMapBuffer :: Integral a => CLCommandQueue -> CLMem -> Bool -> [CLMapFlag] -> a -> a -> [CLEvent] -> IO (CLEvent, Ptr ())
- clEnqueueMapImage :: Integral a => CLCommandQueue -> CLMem -> Bool -> [CLMapFlag] -> (a, a, a) -> (a, a, a) -> [CLEvent] -> IO (CLEvent, (Ptr (), CSize, CSize))
- clEnqueueUnmapMemObject :: CLCommandQueue -> CLMem -> Ptr () -> [CLEvent] -> IO CLEvent
- clEnqueueNDRangeKernel :: Integral a => CLCommandQueue -> CLKernel -> [a] -> [a] -> [CLEvent] -> IO CLEvent
- clEnqueueTask :: CLCommandQueue -> CLKernel -> [CLEvent] -> IO CLEvent
- clEnqueueNativeKernel :: CLCommandQueue -> (Ptr () -> IO ()) -> Ptr () -> CSize -> [CLMem] -> [Ptr ()] -> [CLEvent] -> IO CLEvent
- clEnqueueMarker :: CLCommandQueue -> IO CLEvent
- clEnqueueWaitForEvents :: CLCommandQueue -> [CLEvent] -> IO ()
- clEnqueueBarrier :: CLCommandQueue -> IO ()
- clFlush :: CLCommandQueue -> IO Bool
- clFinish :: CLCommandQueue -> IO Bool
Types
type CLCommandQueue = Ptr ()Source
data CLCommandQueueProperty Source
-
CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE
, Determines whether the commands queued in the command-queue are executed in-order or out-of-order. If set, the commands in the command-queue are executed out-of-order. Otherwise, commands are executed in-order. -
CL_QUEUE_PROFILING_ENABLE
, Enable or disable profiling of commands in the command-queue. If set, the profiling of commands is enabled. Otherwise profiling of commands is disabled. SeeclGetEventProfilingInfo
for more information.
Command Queue Functions
clCreateCommandQueue :: CLContext -> CLDeviceID -> [CLCommandQueueProperty] -> IO CLCommandQueueSource
Create a command-queue on a specific device.
The OpenCL functions that are submitted to a command-queue are enqueued in the order the calls are made but can be configured to execute in-order or out-of-order. The properties argument in clCreateCommandQueue can be used to specify the execution order.
If the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE
property of a command-queue is
not set, the commands enqueued to a command-queue execute in order. For example,
if an application calls clEnqueueNDRangeKernel
to execute kernel A followed by
a clEnqueueNDRangeKernel
to execute kernel B, the application can assume that
kernel A finishes first and then kernel B is executed. If the memory objects
output by kernel A are inputs to kernel B then kernel B will see the correct
data in memory objects produced by execution of kernel A. If the
CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE
property of a commandqueue is set, then
there is no guarantee that kernel A will finish before kernel B starts execution.
Applications can configure the commands enqueued to a command-queue to execute
out-of-order by setting the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE
property of
the command-queue. This can be specified when the command-queue is created or
can be changed dynamically using clCreateCommandQueue
. In out-of-order
execution mode there is no guarantee that the enqueued commands will finish
execution in the order they were queued. As there is no guarantee that kernels
will be executed in order, i.e. based on when the clEnqueueNDRangeKernel
calls
are made within a command-queue, it is therefore possible that an earlier
clEnqueueNDRangeKernel
call to execute kernel A identified by event A may
execute and/or finish later than a clEnqueueNDRangeKernel
call to execute
kernel B which was called by the application at a later point in time. To
guarantee a specific order of execution of kernels, a wait on a particular event
(in this case event A) can be used. The wait for event A can be specified in the
event_wait_list argument to clEnqueueNDRangeKernel
for kernel B.
In addition, a wait for events or a barrier command can be enqueued to the command-queue. The wait for events command ensures that previously enqueued commands identified by the list of events to wait for have finished before the next batch of commands is executed. The barrier command ensures that all previously enqueued commands in a command-queue have finished execution before the next batch of commands is executed.
Similarly, commands to read, write, copy or map memory objects that are enqueued
after clEnqueueNDRangeKernel
, clEnqueueTask
or clEnqueueNativeKernel
commands are not guaranteed to wait for kernels scheduled for execution to have
completed (if the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE
property is set). To
ensure correct ordering of commands, the event object returned by
clEnqueueNDRangeKernel
, clEnqueueTask
or clEnqueueNativeKernel
can be
used to enqueue a wait for event or a barrier command can be enqueued that must
complete before reads or writes to the memory object(s) occur.
clRetainCommandQueue :: CLCommandQueue -> IO BoolSource
Increments the command_queue reference count. clCreateCommandQueue
performs an implicit retain. This is very helpful for 3rd party libraries, which
typically get a command-queue passed to them by the application. However, it is
possible that the application may delete the command-queue without informing the
library. Allowing functions to attach to (i.e. retain) and release a
command-queue solves the problem of a command-queue being used by a library no
longer being valid. Returns True
if the function is executed successfully. It
returns False
if command_queue is not a valid command-queue.
clReleaseCommandQueue :: CLCommandQueue -> IO BoolSource
Decrements the command_queue reference count.
After the command_queue reference count becomes zero and all commands queued
to command_queue have finished (e.g., kernel executions, memory object
updates, etc.), the command-queue is deleted.
Returns True
if the function is executed successfully. It returns False
if command_queue is not a valid command-queue.
clGetCommandQueueContext :: CLCommandQueue -> IO CLContextSource
Return the context specified when the command-queue is created.
This function execute OpenCL clGetCommandQueueInfo with CL_QUEUE_CONTEXT
.
clGetCommandQueueDevice :: CLCommandQueue -> IO CLDeviceIDSource
Return the device specified when the command-queue is created.
This function execute OpenCL clGetCommandQueueInfo with CL_QUEUE_DEVICE
.
clGetCommandQueueReferenceCount :: CLCommandQueue -> IO CLuintSource
Return the command-queue reference count. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.
This function execute OpenCL clGetCommandQueueInfo with
CL_QUEUE_REFERENCE_COUNT
.
clGetCommandQueueProperties :: CLCommandQueue -> IO [CLCommandQueueProperty]Source
Return the currently specified properties for the command-queue. These
properties are specified by the properties argument in clCreateCommandQueue
, and can be changed by clSetCommandQueueProperty
.
This function execute OpenCL clGetCommandQueueInfo with
CL_QUEUE_PROPERTIES
.
clSetCommandQueueProperty :: CLCommandQueue -> [CLCommandQueueProperty] -> Bool -> IO [CLCommandQueueProperty]Source
Enable or disable the properties of a command-queue. Returns the
command-queue properties before they were changed by
clSetCommandQueueProperty
. As specified for clCreateCommandQueue
, the
CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE
command-queue property determines
whether the commands in a command-queue are executed in-order or
out-of-order. Changing this command-queue property will cause the OpenCL
implementation to block until all previously queued commands in command_queue
have completed. This can be an expensive operation and therefore changes to the
CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE
property should be only done when
absolutely necessary.
It is possible that a device(s) becomes unavailable after a context and command-queues that use this device(s) have been created and commands have been queued to command-queues. In this case the behavior of OpenCL API calls that use this context (and command-queues) are considered to be implementation-defined. The user callback function, if specified when the context is created, can be used to record appropriate information when the device becomes unavailable.
Memory Commands
clEnqueueReadBuffer :: Integral a => CLCommandQueue -> CLMem -> Bool -> a -> a -> Ptr () -> [CLEvent] -> IO CLEventSource
Enqueue commands to read from a buffer object to host memory. Calling
clEnqueueReadBuffer to read a region of the buffer object with the ptr argument
value set to host_ptr + offset, where host_ptr is a pointer to the memory region
specified when the buffer object being read is created with
CL_MEM_USE_HOST_PTR
, must meet the following requirements in order to avoid
undefined behavior:
- All commands that use this buffer object have finished execution before the read command begins execution
- The buffer object is not mapped
- The buffer object is not used by any command-queue until the read command has finished execution Errors
clEnqueueReadBuffer
returns the event if the function is executed
successfully. It can throw the following CLError
exceptions:
-
CL_INVALID_COMMAND_QUEUE
if command_queue is not a valid command-queue. -
CL_INVALID_CONTEXT
if the context associated with command_queue and buffer 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 buffer is not a valid buffer object. -
CL_INVALID_VALUE
if the region being read specified by (offset, cb) is out of bounds or if ptr is a NULL value. -
CL_INVALID_EVENT_WAIT_LIST
if event_wait_list is NULL and num_events_in_wait_list greater than 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_MEM_OBJECT_ALLOCATION_FAILURE
if there is a failure to allocate memory for data store associated with buffer. -
CL_OUT_OF_HOST_MEMORY
if there is a failure to allocate resources required by the OpenCL implementation on the host.
clEnqueueWriteBuffer :: Integral a => CLCommandQueue -> CLMem -> Bool -> a -> a -> Ptr () -> [CLEvent] -> IO CLEventSource
Enqueue commands to write to a buffer object from host memory.Calling
clEnqueueWriteBuffer to update the latest bits in a region of the buffer object
with the ptr argument value set to host_ptr + offset, where host_ptr is a
pointer to the memory region specified when the buffer object being written is
created with CL_MEM_USE_HOST_PTR
, must meet the following requirements in
order to avoid undefined behavior:
- The host memory region given by (host_ptr + offset, cb) contains the latest bits when the enqueued write command begins execution.
- The buffer object is not mapped.
- The buffer object is not used by any command-queue until the write command has finished execution.
clEnqueueWriteBuffer
returns the Event if the function is executed
successfully. It can throw the following CLError
exceptions:
-
CL_INVALID_COMMAND_QUEUE
if command_queue is not a valid command-queue. -
CL_INVALID_CONTEXT
if the context associated with command_queue and buffer 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 buffer is not a valid buffer object. -
CL_INVALID_VALUE
if the region being written specified by (offset, cb) is out of bounds or if ptr is a NULL value. -
CL_INVALID_EVENT_WAIT_LIST
if event_wait_list is NULL and num_events_in_wait_list greater than 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_MEM_OBJECT_ALLOCATION_FAILURE
if there is a failure to allocate memory for data store associated with buffer. -
CL_OUT_OF_HOST_MEMORY
if there is a failure to allocate resources required by the OpenCL implementation on the host.
:: Integral a | |
=> CLCommandQueue | Refers to the command-queue in which the read command will be queued. command_queue and image must be created with the same OpenCL contex |
-> CLMem | Refers to a valid 2D or 3D image object. |
-> Bool | Indicates if the read operations are blocking or non-blocking. |
-> (a, a, a) | Defines the (x, y, z) offset in pixels in the image from where to read. If image is a 2D image object, the z value given must be 0. |
-> (a, a, a) | Defines the (width, height, depth) in pixels of the 2D or 3D rectangle being read. If image is a 2D image object, the depth value given must be 1. |
-> a | The length of each row in bytes. This value must be greater than or equal to the element size in bytes * width. If row_pitch is set to 0, the appropriate row pitch is calculated based on the size of each element in bytes multiplied by width. |
-> a | Size in bytes of the 2D slice of the 3D region of a 3D image being read. This must be 0 if image is a 2D image. This value must be greater than or equal to row_pitch * height. If slice_pitch is set to 0, the appropriate slice pitch is calculated based on the row_pitch * height. |
-> Ptr () | The pointer to a buffer in host memory where image data is to be read from. |
-> [CLEvent] | Specify events that need to complete before this particular command can be executed. If event_wait_list is empty, then this particular command does not wait on any event to complete. The events specified in the list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same. |
-> IO CLEvent |
Enqueues a command to read from a 2D or 3D image object to host memory.
Returns an event object that identifies this particular read 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.
Notes
If blocking is True
i.e. the read command is blocking, clEnqueueReadImage
does not return until the buffer data has been read and copied into memory
pointed to by ptr.
If blocking_read is False
i.e. map operation is non-blocking,
clEnqueueReadImage
queues a non-blocking read command and returns. The
contents of the buffer that ptr points to cannot be used until the read command
has completed. The event argument returns an event object which can be used to
query the execution status of the read command. When the read command has
completed, the contents of the buffer that ptr points to can be used by the
application.
Calling clEnqueueReadImage
to read a region of the image object with the ptr
argument value set to host_ptr + (origin.z * image slice pitch + origin.y *
image row pitch + origin.x * bytes per pixel), where host_ptr is a pointer to
the memory region specified when the image object being read is created with
CL_MEM_USE_HOST_PTR
, must meet the following requirements in order to avoid
undefined behavior:
- All commands that use this image object have finished execution before the read command begins execution.
- The row_pitch and slice_pitch argument values in clEnqueueReadImage must be set to the image row pitch and slice pitch.
- The image object is not mapped.
- The image object is not used by any command-queue until the read command has finished execution.
clEnqueueReadImage
returns the CLEvent
if the function is executed
successfully. It can throw the following CLError
exceptions:
-
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 read specified by origin and region is out of bounds or if ptr is a nullPtr value. -
CL_INVALID_VALUE
if image is a 2D image object and z is not equal to 0 or depth is not equal to 1 or slice_pitch is not equal to 0. -
CL_INVALID_EVENT_WAIT_LIST
if event objects in event_wait_list are not valid events. -
CL_MEM_OBJECT_ALLOCATION_FAILURE
if there is a failure to allocate memory for data store associated with image. -
CL_OUT_OF_HOST_MEMORY
if there is a failure to allocate resources required by the OpenCL implementation on the host.
:: Integral a | |
=> CLCommandQueue | Refers to the command-queue in which the write command will be queued. command_queue and image must be created with the same OpenCL contex |
-> CLMem | Refers to a valid 2D or 3D image object. |
-> Bool | Indicates if the write operation is blocking or non-blocking. |
-> (a, a, a) | Defines the (x, y, z) offset in pixels in the image from where to write or write. If image is a 2D image object, the z value given must be 0. |
-> (a, a, a) | Defines the (width, height, depth) in pixels of the 2D or 3D rectangle being write or written. If image is a 2D image object, the depth value given must be 1. |
-> a | The length of each row in bytes. This value must be greater than or equal to the element size in bytes * width. If input_row_pitch is set to 0, the appropriate row pitch is calculated based on the size of each element in bytes multiplied by width. |
-> a | Size in bytes of the 2D slice of the 3D region of a 3D image being written. This must be 0 if image is a 2D image. This value must be greater than or equal to row_pitch * height. If input_slice_pitch is set to 0, the appropriate slice pitch is calculated based on the row_pitch * height. |
-> Ptr () | The pointer to a buffer in host memory where image data is to be written to. |
-> [CLEvent] | Specify events that need to complete before this particular command can be executed. If event_wait_list is empty, then this particular command does not wait on any event to complete. 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. |
-> IO CLEvent |
Enqueues a command to write from a 2D or 3D image object to host memory.
Returns an event object that identifies this particular write 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.
Notes
If blocking_write is True
the OpenCL implementation copies the data referred
to by ptr and enqueues the write command in the command-queue. The memory
pointed to by ptr can be reused by the application after the
clEnqueueWriteImage
call returns.
If blocking_write is False
the OpenCL implementation will use ptr to perform a
nonblocking write. As the write is non-blocking the implementation can return
immediately. The memory pointed to by ptr cannot be reused by the application
after the call returns. The event argument returns an event object which can be
used to query the execution status of the write command. When the write command
has completed, the memory pointed to by ptr can then be reused by the
application.
Calling clEnqueueWriteImage
to update the latest bits in a region of the image
object with the ptr argument value set to host_ptr + (origin.z * image slice
pitch + origin.y * image row pitch + origin.x * bytes per pixel), where host_ptr
is a pointer to the memory region specified when the image object being written
is created with CL_MEM_USE_HOST_PTR
, must meet the following requirements in
order to avoid undefined behavior:
- The host memory region being written contains the latest bits when the enqueued write command begins execution.
- The input_row_pitch and input_slice_pitch argument values in clEnqueueWriteImage must be set to the image row pitch and slice pitch.
- The image object is not mapped.
- The image object is not used by any command-queue until the write command has finished execution.
clEnqueueWriteImage
returns the CLEvent
if the function is executed
successfully. It can throw the following CLError
exceptions:
-
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 write or written specified by origin and region is out of bounds or if ptr is a NULL value. -
CL_INVALID_VALUE
if image is a 2D image object and z is not equal to 0 or depth is not equal to 1 or slice_pitch is not equal to 0. -
CL_INVALID_EVENT_WAIT_LIST
if event objects in event_wait_list are not valid events. -
CL_MEM_OBJECT_ALLOCATION_FAILURE
if there is a failure to allocate memory for data store associated with image. -
CL_OUT_OF_HOST_MEMORY
if there is a failure to allocate resources required by the OpenCL implementation on the host.
:: Integral a | |
=> CLCommandQueue | Refers to the command-queue in which the copy command will be queued. The OpenCL context associated with command_queue, src_image and dst_image must be the same. |
-> CLMem | src |
-> CLMem | dst |
-> (a, a, a) | Defines the starting (x, y, z) location in pixels in src_image from where to start the data copy. If src_image is a 2D image object, the z value given must be 0. |
-> (a, a, a) | Defines the starting (x, y, z) location in pixels in dst_image from where to start the data copy. If dst_image is a 2D image object, the z value given must be 0. |
-> (a, a, a) | Defines the (width, height, depth) in pixels of the 2D or 3D rectangle to copy. If src_image or dst_image is a 2D image object, the depth value given must be 1. |
-> [CLEvent] | Specify events that need to complete before this particular command can be executed. If event_wait_list is empty, then this particular command does not wait on any event to complete. |
-> IO CLEvent |
Enqueues a command to copy image objects.
Notes
It is currently a requirement that the src_image and dst_image image memory
objects for clEnqueueCopyImage
must have the exact same image format (i.e. the
CLImageFormat
descriptor specified when src_image and dst_image are created
must match).
src_image and dst_image can be 2D or 3D image objects allowing us to perform the following actions:
- Copy a 2D image object to a 2D image object.
- Copy a 2D image object to a 2D slice of a 3D image object.
- Copy a 2D slice of a 3D image object to a 2D image object.
- Copy a 3D image object to a 3D image object.
clEnqueueCopyImage
returns the CLEvent
if the function is executed
successfully. It can throw the following CLError
exceptions:
- 'CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
- 'CL_INVALID_CONTEXT if the context associated with command_queue, src_image and dst_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 src_image and dst_image are not valid image objects.
- 'CL_IMAGE_FORMAT_MISMATCH if src_image and dst_image do not use the same image format.
- 'CL_INVALID_VALUE if the 2D or 3D rectangular region specified by src_origin and src_origin + region refers to a region outside src_image, or if the 2D or 3D rectangular region specified by dst_origin and dst_origin + region refers to a region outside dst_image.
- 'CL_INVALID_VALUE if src_image is a 2D image object and src_origin.z is not equal to 0 or region.depth is not equal to 1.
- 'CL_INVALID_VALUE if dst_image is a 2D image object and dst_origen.z is not equal to 0 or region.depth is not equal to 1.
- 'CL_INVALID_EVENT_WAIT_LIST if event objects in event_wait_list are not valid events.
- 'CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with src_image or dst_image.
- 'CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
- 'CL_MEM_COPY_OVERLAP if src_image and dst_image are the same image object and the source and destination regions overlap.
clEnqueueCopyImageToBufferSource
:: Integral a | |
=> CLCommandQueue | The OpenCL context associated with command_queue, src_image, and dst_buffer must be the same. |
-> CLMem | src. A valid image object. |
-> CLMem | dst. A valid buffer object. |
-> (a, a, a) | Defines the (x, y, z) offset in pixels in the image from where to copy. If src_image is a 2D image object, the z value given must be 0. |
-> (a, a, a) | Defines the (width, height, depth) in pixels of the 2D or 3D rectangle to copy. If src_image is a 2D image object, the depth value given must be 1. |
-> a | The offset where to begin copying data into dst_buffer. The size in bytes of the region to be copied referred to as dst_cb is computed as width * height * depth * bytes/image element if src_image is a 3D image object and is computed as width * height * bytes/image element if src_image is a 2D image object. |
-> [CLEvent] | Specify events that need to complete before this particular command can be executed. If event_wait_list is empty, then this particular command does not wait on any event to complete. 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. |
-> IO CLEvent |
Enqueues a command to copy an image object to a buffer object.
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. clEnqueueBarrier
can be used instead.
clEnqueueCopyImageToBuffer
returns the CLEvent
if the function is executed
successfully. It can throw the following CLError
exceptions:
- CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
- CL_INVALID_CONTEXT if the context associated with command_queue, src_image and dst_buffer 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 src_image is not a valid image object and dst_buffer is not a valid buffer object.
- CL_INVALID_VALUE if the 2D or 3D rectangular region specified by src_origin and src_origin + region refers to a region outside src_image, or if the region specified by dst_offset and dst_offset + dst_cb refers to a region outside dst_buffer.
- CL_INVALID_VALUE if src_image is a 2D image object and src_origin.z is not equal to 0 or region.depth is not equal to 1.
- CL_INVALID_EVENT_WAIT_LIST if event objects in event_wait_list are not valid events.
- CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with src_image or dst_buffer.
- CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
clEnqueueCopyBufferToImageSource
:: Integral a | |
=> CLCommandQueue | The OpenCL context associated with command_queue, src_image, and dst_buffer must be the same. |
-> CLMem | src. A valid buffer object. |
-> CLMem | dst. A valid image object. |
-> a | The offset where to begin copying data from src_buffer. |
-> (a, a, a) | The (x, y, z) offset in pixels where to begin copying data to dst_image. If dst_image is a 2D image object, the z value given by must be 0. |
-> (a, a, a) | Defines the (width, height, depth) in pixels of the 2D or 3D rectangle to copy. If dst_image is a 2D image object, the depth value given by must be 1. |
-> [CLEvent] | Specify events that need to complete before this particular command can be executed. If event_wait_list is empty, then this particular command does not wait on any event to complete. 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. |
-> IO CLEvent |
Enqueues a command to copy a buffer object to an image object.
The size in bytes of the region to be copied from src_buffer referred to as src_cb is computed as width * height * depth * bytes/image element if dst_image is a 3D image object and is computed as width * height * bytes/image element if dst_image is a 2D image object.
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. clEnqueueBarrier
can be used instead.
clEnqueueCopyBufferToImage
returns the CLEvent
if the function is executed
successfully. It can throw the following CLError
exceptions:
-
CL_INVALID_COMMAND_QUEUE
if command_queue is not a valid command-queue. -
CL_INVALID_CONTEXT
if the context associated with command_queue, src_buffer and dst_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 src_buffer is not a valid buffer object and dst_image is not a valid image object. -
CL_INVALID_VALUE
if the 2D or 3D rectangular region specified by dst_origin and dst_origin + region refers to a region outside dst_origin, or if the region specified by src_offset and src_offset + src_cb refers to a region outside src_buffer. -
CL_INVALID_VALUE
if dst_image is a 2D image object and dst_origin.z is not equal to 0 or region.depth is not equal to 1. -
CL_INVALID_EVENT_WAIT_LIST
if event objects in event_wait_list are not valid events. -
CL_MEM_OBJECT_ALLOCATION_FAILURE
if there is a failure to allocate memory for data store associated with src_buffer or dst_image. -
CL_OUT_OF_HOST_MEMORY
if there is a failure to allocate resources required by the OpenCL implementation on the host.
:: Integral a | |
=> CLCommandQueue | |
-> CLMem | A valid buffer object. The OpenCL context associated with command_queue and buffer must be the same. |
-> Bool | Indicates if the map operation is blocking or non-blocking. |
-> [CLMapFlag] | Is a list and can be set to
|
-> a | The offset in bytes of the region in the buffer object that is being mapped. |
-> a | The size in bytes of the region in the buffer object that is being mapped. |
-> [CLEvent] | Specify events that need to complete before this particular command can be executed. If event_wait_list is empty, then this particular command does not wait on any event to complete. 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. |
-> IO (CLEvent, Ptr ()) |
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.
If blocking_map is True
, clEnqueueMapBuffer
does not return until the
specified region in buffer can be mapped.
If blocking_map is 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
.
Returns an event object that identifies this particular copy command and can be used toquery 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.
The contents of the regions of a memory object mapped for writing
(i.e. CL_MAP_WRITE
is set in map_flags argument to clEnqueueMapBuffer
or
clEnqueueMapImage
) are considered to be undefined until this region is
unmapped. Reads and writes by a kernel executing on a device to a memory
region(s) mapped for writing are undefined.
Multiple command-queues can map a region or overlapping regions of a memory
object for reading (i.e. map_flags = CL_MAP_READ
). The contents of the regions
of a memory object mapped for reading can also be read by kernels executing on a
device(s). The behavior of writes by a kernel executing on a device to a mapped
region of a memory object is undefined. Mapping (and unmapping) overlapped
regions of a buffer or image memory object for writing is undefined.
The behavior of OpenCL function calls that enqueue commands that write or copy to regions of a memory object that are mapped is undefined.
clEnqueueMapBuffer
will return a pointer to the mapped region if the function
is executed successfully. A nullPtr pointer is returned otherwise with one of
the following exception:
-
CL_INVALID_COMMAND_QUEUE
if command_queue is not a valid command-queue. -
CL_INVALID_CONTEXT
if the context associated with command_queue, src_image and dst_buffer 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 buffer is not a valid buffer object. -
CL_INVALID_VALUE
if region being mapped given by (offset, cb) is out of bounds or if values specified in map_flags are not valid -
CL_INVALID_EVENT_WAIT_LIST
if event objects in event_wait_list are not valid events. -
CL_MAP_FAILURE
if there is a failure to map the requested region into the host address space. This error cannot occur for buffer objects created withCL_MEM_USE_HOST_PTR
orCL_MEM_ALLOC_HOST_PTR
. -
CL_MEM_OBJECT_ALLOCATION_FAILURE
if there is a failure to allocate memory for data store associated with buffer. -
CL_OUT_OF_HOST_MEMORY
if there is a failure to allocate resources required by the OpenCL implementation on the host.
The pointer returned maps a region starting at offset and is atleast cb bytes in size. The result of a memory access outside this region is undefined.
:: Integral a | |
=> CLCommandQueue | |
-> CLMem | A valid image object. The OpenCL context associated with command_queue and image must be the same. |
-> Bool | Indicates if the map operation is blocking or
non-blocking. If blocking_map is |
-> [CLMapFlag] | Is a bit-field and can be set to
|
-> (a, a, a) | Define the (x, y, z) offset in pixels of the 2D or 3D rectangle region that is to be mapped. If image is a 2D image object, the z value given must be 0. |
-> (a, a, a) | Define the (width, height, depth) in pixels of the 2D or 3D rectangle region that is to be mapped. If image is a 2D image object, the depth value given must be 1. |
-> [CLEvent] | Specify events that need to complete
before |
-> IO (CLEvent, (Ptr (), CSize, CSize)) |
Enqueues a command to map a region of an image object into the host address space and returns a pointer to this mapped region.
If blocking_map is False
i.e. map operation is non-blocking, the pointer to
the mapped region returned by clEnqueueMapImage
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 clEnqueueMapImage
.
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 buffer or image object is created with CL_MEM_USE_HOST_PTR
set in
mem_flags, the following will be true:
- The host_ptr specified in
clCreateBuffer
,clCreateImage2D
, orclCreateImage3D
is guaranteed to contain the latest bits in the region being mapped when theclEnqueueMapBuffer
orclEnqueueMapImage
command has completed. - The pointer value returned by
clEnqueueMapBuffer
orclEnqueueMapImage
will be derived from the host_ptr specified when the buffer or image object is created.
The contents of the regions of a memory object mapped for writing
(i.e. CL_MAP_WRITE
is set in map_flags argument to clEnqueueMapBuffer
or
clEnqueueMapImage
) are considered to be undefined until this region is
unmapped. Reads and writes by a kernel executing on a device to a memory
region(s) mapped for writing are undefined.
Multiple command-queues can map a region or overlapping regions of a memory
object for reading (i.e. map_flags = CL_MAP_READ
). The contents of the regions
of a memory object mapped for reading can also be read by kernels executing on a
device(s). The behavior of writes by a kernel executing on a device to a mapped
region of a memory object is undefined. Mapping (and unmapping) overlapped
regions of a buffer or image memory object for writing is undefined.
The behavior of OpenCL function calls that enqueue commands that write or copy to regions of a memory object that are mapped is undefined.
clEnqueueMapImage
will return a pointer to the mapped region if the
function is executed successfully also the scan-line (row) pitch in bytes for
the mapped region and the size in bytes of each 2D slice for the mapped
region. For a 2D image, zero is returned as slice pitch. A nullPtr pointer is
returned otherwise with one of the following exception:
-
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 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 image is a 2D image object and z is not equal to 0 or depth is not equal to 1. -
CL_INVALID_EVENT_WAIT_LIST
if event objects in event_wait_list are not valid events. -
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 withCL_MEM_USE_HOST_PTR
orCL_MEM_ALLOC_HOST_PTR
. -
CL_MEM_OBJECT_ALLOCATION_FAILURE
if there is a failure to allocate memory for data store associated with image. -
CL_OUT_OF_HOST_MEMORY
if there is a failure to allocate resources required by the OpenCL implementation on the host.
The pointer returned maps a 2D or 3D region starting at origin and is atleast (image_row_pitch * y + x) pixels in size for a 2D image, and is atleast (image_slice_pitch * z] + image_row_pitch * y + x) pixels in size for a 3D image. The result of a memory access outside this region is undefined.
:: CLCommandQueue | |
-> CLMem | A valid memory object. The OpenCL context associated with command_queue and memobj must be the same. |
-> Ptr () | The host address returned by a
previous call to |
-> [CLEvent] | Specify events that need to
complete before
|
-> IO CLEvent |
Enqueues a command to unmap a previously mapped region of a memory object.
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. clEnqueueBarrier
can be used instead.
Reads or writes from the host using the pointer returned by clEnqueueMapBuffer
or clEnqueueMapImage
are considered to be complete.
clEnqueueMapBuffer
and clEnqueueMapImage
increments 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 memory object being mapped.
clEnqueueUnmapMemObject
returns the CLEvent
if the function is executed
successfully. It can throw the following CLError
exceptions:
- CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
- CL_INVALID_MEM_OBJECT if memobj is not a valid memory object.
- CL_INVALID_VALUE if mapped_ptr is not a valid pointer returned by
clEnqueueMapBuffer
orclEnqueueMapImage
for memobj. - CL_INVALID_EVENT_WAIT_LIST if event objects in event_wait_list are not valid events.
- CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
- CL_INVALID_CONTEXT if the 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.
Executing Kernels
clEnqueueNDRangeKernel :: Integral a => CLCommandQueue -> CLKernel -> [a] -> [a] -> [CLEvent] -> IO CLEventSource
Enqueues a command to execute a kernel on a device. Each work-item is uniquely identified by a global identifier. The global ID, which can be read inside the kernel, is computed using the value given by global_work_size and global_work_offset. In OpenCL 1.0, the starting global ID is always (0, 0, ... 0). In addition, a work-item is also identified within a work-group by a unique local ID. The local ID, which can also be read by the kernel, is computed using the value given by local_work_size. The starting local ID is always (0, 0, ... 0).
Returns the event if the kernel execution was successfully queued. It can throw
the following CLError
exceptions:
-
CL_INVALID_PROGRAM_EXECUTABLE
if there is no successfully built program executable available for device associated with command_queue. -
CL_INVALID_COMMAND_QUEUE
if command_queue is not a valid command-queue. -
CL_INVALID_KERNEL
if kernel is not a valid kernel object. -
CL_INVALID_CONTEXT
if context associated with command_queue and kernel is not the same or if the context associated with command_queue and events in event_wait_list are not the same. -
CL_INVALID_KERNEL_ARGS
if the kernel argument values have not been specified. -
CL_INVALID_WORK_DIMENSION
if work_dim is not a valid value (i.e. a value between 1 and 3). -
CL_INVALID_WORK_GROUP_SIZE
if local_work_size is specified and number of work-items specified by global_work_size is not evenly divisable by size of work-group given by local_work_size or does not match the work-group size specified for kernel using the __attribute__((reqd_work_group_size(X, Y, Z))) qualifier in program source. -
CL_INVALID_WORK_GROUP_SIZE
if local_work_size is specified and the total number of work-items in the work-group computed as local_work_size[0] *... local_work_size[work_dim - 1] is greater than the value specified byCL_DEVICE_MAX_WORK_GROUP_SIZE
in the table of OpenCL Device Queries for clGetDeviceInfo. -
CL_INVALID_WORK_GROUP_SIZE
if local_work_size is NULL and the __attribute__((reqd_work_group_size(X, Y, Z))) qualifier is used to declare the work-group size for kernel in the program source. -
CL_INVALID_WORK_ITEM_SIZE
if the number of work-items specified in any of local_work_size[0], ... local_work_size[work_dim - 1] is greater than the corresponding values specified byCL_DEVICE_MAX_WORK_ITEM_SIZES
[0], ....CL_DEVICE_MAX_WORK_ITEM_SIZES
[work_dim - 1]. -
CL_OUT_OF_RESOURCES
if there is a failure to queue the execution instance of kernel on the command-queue because of insufficient resources needed to execute the kernel. For example, the explicitly specified local_work_size causes a failure to execute the kernel because of insufficient resources such as registers or local memory. Another example would be the number of read-only image args used in kernel exceed theCL_DEVICE_MAX_READ_IMAGE_ARGS
value for device or the number of write-only image args used in kernel exceed theCL_DEVICE_MAX_WRITE_IMAGE_ARGS
value for device or the number of samplers used in kernel exceedCL_DEVICE_MAX_SAMPLERS
for device. -
CL_MEM_OBJECT_ALLOCATION_FAILURE
if there is a failure to allocate memory for data store associated with image or buffer objects specified as arguments to kernel. -
CL_OUT_OF_HOST_MEMORY
if there is a failure to allocate resources required by the OpenCL implementation on the host.
clEnqueueTask :: CLCommandQueue -> CLKernel -> [CLEvent] -> IO CLEventSource
Enqueues a command to execute a kernel on a device. The kernel is executed using a single work-item.
clEnqueueTask
is equivalent to calling clEnqueueNDRangeKernel
with work_dim
= 1, global_work_offset = [], global_work_size[0] set to 1, and
local_work_size[0] set to 1.
Returns the evens if the kernel execution was successfully queued. It can throw
the following CLError
exceptions:
-
CL_INVALID_PROGRAM_EXECUTABLE
if there is no successfully built program executable available for device associated with command_queue. - 'CL_INVALID_COMMAND_QUEUE if' command_queue is not a valid command-queue.
-
CL_INVALID_KERNEL
if kernel is not a valid kernel object. -
CL_INVALID_CONTEXT
if context associated with command_queue and kernel is not the same or if the context associated with command_queue and events in event_wait_list are not the same. -
CL_INVALID_KERNEL_ARGS
if the kernel argument values have not been specified. -
CL_INVALID_WORK_GROUP_SIZE
if a work-group size is specified for kernel using the __attribute__((reqd_work_group_size(X, Y, Z))) qualifier in program source and is not (1, 1, 1). -
CL_OUT_OF_RESOURCES
if there is a failure to queue the execution instance of kernel on the command-queue because of insufficient resources needed to execute the kernel. -
CL_MEM_OBJECT_ALLOCATION_FAILURE
if there is a failure to allocate memory for data store associated with image or buffer objects specified as arguments to kernel. -
CL_OUT_OF_HOST_MEMORY
if there is a failure to allocate resources required by the OpenCL implementation on the host.
clEnqueueNativeKernel :: CLCommandQueue -> (Ptr () -> IO ()) -> Ptr () -> CSize -> [CLMem] -> [Ptr ()] -> [CLEvent] -> IO CLEventSource
Enqueues a command to execute a native C/C++ function not compiled using the
OpenCL compiler. A native user function can only be executed on a command-queue
created on a device that has CL_EXEC_NATIVE_KERNEL
capability set in
clGetDeviceExecutionCapabilities
.
The data pointed to by args and cb_args bytes in size will be copied and a
pointer to this copied region will be passed to user_func. The copy needs to be
done because the memory objects (CLMem
values) that args may contain need to
be modified and replaced by appropriate pointers to global memory. When
clEnqueueNativeKernel
returns, the memory region pointed to by args can be
reused by the application.
Returns the evens if the kernel execution was successfully queued. It can throw
the following CLError
exceptions:
-
CL_INVALID_COMMAND_QUEUE
if command_queue is not a valid command-queue. -
CL_INVALID_CONTEXT
if context associated with command_queue and events in event-wait_list are not the same. -
CL_INVALID_VALUE
if args is a NULL value and cb_args is greater than 0, or if args is a NULL value and num_mem_objects is greater than 0. -
CL_INVALID_VALUE
if args is not NULL and cb_args is 0. -
CL_INVALID_OPERATION
if device cannot execute the native kernel. -
CL_INVALID_MEM_OBJECT
if one or more memory objects specified in mem_list are not valid or are not buffer objects. -
CL_OUT_OF_RESOURCES
if there is a failure to queue the execution instance of kernel on the command-queue because of insufficient resources needed to execute the kernel. -
CL_MEM_OBJECT_ALLOCATION_FAILURE
if there is a failure to allocate memory for data store associated with buffer objects specified as arguments to kernel. -
CL_INVALID_EVENT_WAIT_LIST
if event objects in event_wait_list are not valid events. -
CL_OUT_OF_HOST_MEMORY
if there is a failure to allocate resources required by the OpenCL implementation on the host.
clEnqueueMarker :: CLCommandQueue -> IO CLEventSource
Enqueues a marker command to command_queue. The marker command returns an
event which can be used to queue a wait on this marker event i.e. wait for
all commands queued before the marker command to complete. Returns the event
if the function is successfully executed. It throw the CLError
exception
CL_INVALID_COMMAND_QUEUE
if command_queue is not a valid command-queue and
throw CL_OUT_OF_HOST_MEMORY
if there is a failure to allocate resources
required by the OpenCL implementation on the host.
clEnqueueWaitForEvents :: CLCommandQueue -> [CLEvent] -> IO ()Source
Enqueues a wait for a specific event or a list of events to complete before any future commands queued in the command-queue are executed. The context associated with events in event_list and command_queue must be the same.
It can throw the following CLError
exceptions:
-
CL_INVALID_COMMAND_QUEUE
if command_queue is not a valid command-queue. -
CL_INVALID_CONTEXT
if the context associated with command_queue and events in event_list are not the same. -
CL_INVALID_VALUE
if num_events is zero. -
CL_INVALID_EVENT
if event objects specified in event_list are not valid events. -
CL_OUT_OF_HOST_MEMORY
if there is a failure to allocate resources required by the OpenCL implementation on the host.
clEnqueueBarrier :: CLCommandQueue -> IO ()Source
clEnqueueBarrier
is a synchronization point that ensures that all queued
commands in command_queue have finished execution before the next batch of
commands can begin execution. It throws CL_INVALID_COMMAND_QUEUE
if
command_queue is not a valid command-queue and throws
CL_OUT_OF_HOST_MEMORY
if there is a failure to allocate resources required
by the OpenCL implementation on the host.
Flush and Finish
clFlush :: CLCommandQueue -> IO BoolSource
Issues all previously queued OpenCL commands in a command-queue to the
device associated with the command-queue. clFlush
only guarantees that all
queued commands to command_queue get issued to the appropriate device. There is
no guarantee that they will be complete after clFlush
returns.
clFlush
returns True
if the function call was executed successfully. It
returns False
if command_queue is not a valid command-queue or if there is a
failure to allocate resources required by the OpenCL implementation on the host.
Any blocking commands queued in a command-queue such as clEnqueueReadImage
or
clEnqueueReadBuffer
with blocking_read set to True
, clEnqueueWriteImage
or
clEnqueueWriteBuffer
with blocking_write set to True
, clEnqueueMapImage
or
clEnqueueMapBuffer
with blocking_map set to True
or clWaitForEvents
perform an implicit flush of the command-queue.
To use event objects that refer to commands enqueued in a command-queue as
event objects to wait on by commands enqueued in a different command-queue, the
application must call a clFlush
or any blocking commands that perform an
implicit flush of the command-queue where the commands that refer to these event
objects are enqueued.
clFinish :: CLCommandQueue -> IO BoolSource
Blocks until all previously queued OpenCL commands in a command-queue are
issued to the associated device and have completed.
clFinish
does not return until all queued commands in command_queue have
been processed and completed. clFinish
is also a synchronization point.
clFinish
returns True
if the function call was executed successfully. It
returns False
if command_queue is not a valid command-queue or if there is
a failure to allocate resources required by the OpenCL implementation on the
host.