Platforms to show: All Mac Windows Linux Cross-Platform

Back to CLCommandQueueMBS class.

Next items

CLCommandQueueMBS.Constructor(context as CLContextMBS, device as CLDeviceMBS, flags as Integer = 0)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
Create a command-queue on a specific device.
Example
dim devices(-1) as CLDeviceMBS = OpenCLMBS.AllDevices(CLDeviceMBS.kDeviceTypeGPU)
dim device as CLDeviceMBS = devices(0) // we use first one

// Create a context
dim context as new CLContextMBS(device, CLContextMBS.kErrorModeLogMessagesToSystemLog)

// Create a command queue
dim queue as new CLCommandQueueMBS(context, device, 0)

context: Must be a valid OpenCL context.
device: Must be a device associated with context. It can either be in the list of devices specified when context is created using CLContextMBS Constructor or have the same device type as the device type specified when the context is created.
flags: Specifies a list of properties for the command-queue. This is a bit-field. Only command-queue properties specified in the table below can be set in properties; otherwise the value specified in properties is considered to be not valid.

Command-Queue PropertiesDescription
kQueueOutOfOrderExecModeEnableDetermines 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.
kQueueProfilingEnableEnable or disable profiling of commands in the command-queue. If set, the profiling of commands is enabled. Otherwise profiling of commands is disabled. See clGetEventProfilingInfo for more information.

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 kQueueOutOfOrderExecModeEnable property of a command-queue is not set, the commands enqueued to a command-queue execute in order. For example, if an application calls EnqueueNDRangeKernel to execute kernel A followed by a EnqueueNDRangeKernel 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 kQueueOutOfOrderExecModeEnable 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 kQueueOutOfOrderExecModeEnable property of the command-queue. This can be specified when the command-queue is created or can be changed dynamically using this Constructor. 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 EnqueueNDRangeKernel calls are made within a command-queue, it is therefore possible that an earlier EnqueueNDRangeKernel call to execute kernel A identified by event A may execute and/or finish later than a EnqueueNDRangeKernel 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 EnqueueNDRangeKernel 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 EnqueueNDRangeKernel, EnqueueTask or EnqueueNativeKernel commands are not guaranteed to wait for kernels scheduled for execution to have completed (if the kQueueOutOfOrderExecModeEnable property is set). To ensure correct ordering of commands, the event object returned by EnqueueNDRangeKernel, EnqueueTask or EnqueueNativeKernel 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.

Lasterror is set.

CLCommandQueueMBS.Context as CLContextMBS

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
Return the context specified when the command-queue is created.

Lasterror is set.

CLCommandQueueMBS.Device as CLDeviceMBS

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
Return the device specified when the command-queue is created.

Lasterror is set.

CLCommandQueueMBS.EnqueueBarrier

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
A synchronization point that enqueues a barrier operation.

EnqueueBarrier 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.

Lasterror is set.

CLCommandQueueMBS.EnqueueCopyBuffer(sourceBuffer as CLMemMBS, destBuffer as CLMemMBS, sourceOffset as Integer, destOffset as Integer, size as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
Enqueues a command to copy a buffer object to another buffer object.

sourceBuffer: the source memory object.
destBuffer: the destination memory object.
sourceOffset: The offset where to begin copying data from sourceBuffer.
destOffset: The offset where to begin copying data into destBuffer.
size: Refers to the size in bytes to copy.
EventWaitList: Optional, Specify events that need to complete before this particular command can be executed. If EventWaitList is empty or not passed, 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 EventWaitList and CLCommandQueueMBS must be the same.
outEvent: 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.
Lasterror is set.

See also:

CLCommandQueueMBS.EnqueueCopyBuffer(sourceBuffer as CLMemMBS, destBuffer as CLMemMBS, sourceOffset as Integer, destOffset as Integer, size as Integer, EventWaitList() as CLEventMBS, byref outEvent as CLEventMBS)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
Enqueues a command to copy a buffer object to another buffer object.

sourceBuffer: the source memory object.
destBuffer: the destination memory object.
sourceOffset: The offset where to begin copying data from sourceBuffer.
destOffset: The offset where to begin copying data into destBuffer.
size: Refers to the size in bytes to copy.
EventWaitList: Optional, Specify events that need to complete before this particular command can be executed. If EventWaitList is empty or not passed, 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 EventWaitList and CLCommandQueueMBS must be the same.
outEvent: 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.
Lasterror is set.

See also:

CLCommandQueueMBS.EnqueueCopyBufferToImage(SourceBuffer as CLMemMBS, destImage as CLMemMBS, sourceOffset as Integer, destOriginX as Integer, destOriginY as Integer, destOriginZ as Integer, RegionWidth as Integer, RegionHeight as Integer, RegionDepth as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
Enqueues a command to copy a buffer object to an image object.

SourceBuffer: A valid buffer object.
destImage: A valid image object.

sourceOffset: The offset where to begin copying data from SourceBuffer.

destOrigin: The (x, y, z) offset in pixels where to begin copying data to destImage. If destImage is a 2D image object, the z value given by destOriginZ must be 0.

region: Defines the (width, height, depth) in pixels of the 2D or 3D rectangle to copy. If destImage is a 2D image object, the depth value given by RegionDepth must be 1.

The size in bytes of the region to be copied from SourceBuffer referred to as src_cb is computed as width * height * depth * bytes/image element if destImage is a 3D image object and is computed as width * height * bytes/image element if destImage is a 2D image object.

EventWaitList: Optionally, Specify events that need to complete before this particular command can be executed. 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.

outEvent: Optional. 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.

Lasterror is set.

See also:

CLCommandQueueMBS.EnqueueCopyBufferToImage(SourceBuffer as CLMemMBS, destImage as CLMemMBS, sourceOffset as Integer, destOriginX as Integer, destOriginY as Integer, destOriginZ as Integer, RegionWidth as Integer, RegionHeight as Integer, RegionDepth as Integer, EventWaitList() as CLEventMBS, byref outEvent as CLEventMBS)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
Enqueues a command to copy a buffer object to an image object.

SourceBuffer: A valid buffer object.
destImage: A valid image object.

sourceOffset: The offset where to begin copying data from SourceBuffer.

destOrigin: The (x, y, z) offset in pixels where to begin copying data to destImage. If destImage is a 2D image object, the z value given by destOriginZ must be 0.

region: Defines the (width, height, depth) in pixels of the 2D or 3D rectangle to copy. If destImage is a 2D image object, the depth value given by RegionDepth must be 1.

The size in bytes of the region to be copied from SourceBuffer referred to as src_cb is computed as width * height * depth * bytes/image element if destImage is a 3D image object and is computed as width * height * bytes/image element if destImage is a 2D image object.

EventWaitList: Optionally, Specify events that need to complete before this particular command can be executed. 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.

outEvent: Optional. 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.

Lasterror is set.

See also:

CLCommandQueueMBS.EnqueueCopyImage(sourceImage as CLMemMBS, destImage as CLMemMBS, sourceOriginX as Integer, sourceOriginY as Integer, sourceOriginZ as Integer, destOriginX as Integer, destOriginY as Integer, destOriginZ as Integer, RegionWidth as Integer, RegionHeight as Integer, RegionDepth as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
Enqueues a command to copy image objects.

sourceImage: Source image.
destImage: Dest image.

sourceOrigin: 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 by sourceOriginZ must be 0.

sourceOrigin: 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 by sourceOriginZ must be 0.

region: 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 by RegionDepth must be 1.

EventWaitList: Optional, Specify events that need to complete before this particular command can be executed. The events specified in EventWaitList act as synchronization points. The context associated with events in EventWaitList and CommandQueue must be the same.

outEvent: Optional, 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.

It is currently a requirement that the sourceImage and destImage image memory objects for EnqueueCopyImage must have the exact same image format (i.e. the cl_image_format descriptor specified when sourceImage and destImage are created must match).

sourceImage and destImage 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.

Lasterror is set.

See also:

CLCommandQueueMBS.EnqueueCopyImage(sourceImage as CLMemMBS, destImage as CLMemMBS, sourceOriginX as Integer, sourceOriginY as Integer, sourceOriginZ as Integer, destOriginX as Integer, destOriginY as Integer, destOriginZ as Integer, RegionWidth as Integer, RegionHeight as Integer, RegionDepth as Integer, EventWaitList() as CLEventMBS, byref outEvent as CLEventMBS)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
Enqueues a command to copy image objects.

sourceImage: Source image.
destImage: Dest image.

sourceOrigin: 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 by sourceOriginZ must be 0.

sourceOrigin: 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 by sourceOriginZ must be 0.

region: 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 by RegionDepth must be 1.

EventWaitList: Optional, Specify events that need to complete before this particular command can be executed. The events specified in EventWaitList act as synchronization points. The context associated with events in EventWaitList and CommandQueue must be the same.

outEvent: Optional, 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.

It is currently a requirement that the sourceImage and destImage image memory objects for EnqueueCopyImage must have the exact same image format (i.e. the cl_image_format descriptor specified when sourceImage and destImage are created must match).

sourceImage and destImage 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.

Lasterror is set.

See also:

CLCommandQueueMBS.EnqueueCopyImageToBuffer(sourceImage as CLMemMBS, destBuffer as CLMemMBS, sourceOriginX as Integer, sourceOriginY as Integer, sourceOriginZ as Integer, RegionWidth as Integer, RegionHeight as Integer, RegionDepth as Integer, destOffset as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
Enqueues a command to copy an image object to a buffer object.

sourceImage: A valid image object.
destBuffer: A valid buffer object.

sourceOrigin: Defines the (x, y, z) offset in pixels in the image from where to copy. If sourceImage is a 2D image object, the z value given by sourceOriginZ must be 0.

region: Defines the (width, height, depth) in pixels of the 2D or 3D rectangle to copy. If sourceImage is a 2D image object, the depth value given by RegionDepth must be 1.

destOffset: The offset where to begin copying data into destBuffer. 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 sourceImage is a 3D image object and is computed as width * height * bytes/image element if sourceImage is a 2D image object.

EventWaitList: Specify events that need to complete before this particular command can be executed. 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.

outEvent: 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.

Lasterror is set.

See also:

CLCommandQueueMBS.EnqueueCopyImageToBuffer(sourceImage as CLMemMBS, destBuffer as CLMemMBS, sourceOriginX as Integer, sourceOriginY as Integer, sourceOriginZ as Integer, RegionWidth as Integer, RegionHeight as Integer, RegionDepth as Integer, destOffset as Integer, EventWaitList() as CLEventMBS, byref outEvent as CLEventMBS)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
Enqueues a command to copy an image object to a buffer object.

sourceImage: A valid image object.
destBuffer: A valid buffer object.

sourceOrigin: Defines the (x, y, z) offset in pixels in the image from where to copy. If sourceImage is a 2D image object, the z value given by sourceOriginZ must be 0.

region: Defines the (width, height, depth) in pixels of the 2D or 3D rectangle to copy. If sourceImage is a 2D image object, the depth value given by RegionDepth must be 1.

destOffset: The offset where to begin copying data into destBuffer. 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 sourceImage is a 3D image object and is computed as width * height * bytes/image element if sourceImage is a 2D image object.

EventWaitList: Specify events that need to complete before this particular command can be executed. 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.

outEvent: 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.

Lasterror is set.

See also:

CLCommandQueueMBS.EnqueueMapBuffer(buffer as CLMemMBS, BlockingMap as boolean, MapFlags as Integer, offset as Integer, size as Integer, EventWaitList() as CLEventMBS, byref outEvent as CLEventMBS) as memoryblock

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
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.

BlockingMap: Optional, Indicates if the map operation is blocking or non-blocking. If BlockingMap is true, EnqueueMapBuffer does not return until the specified region in buffer can be mapped. If BlockingMap 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 EnqueueMapBuffer.
MapFlags: Is a bit-field and can be set to kMapRead to indicate that the region specified by (offset, size) in the buffer object is being mapped for reading, and/or kMapWrite to indicate that the region specified by (offset, size) in the buffer object is being mapped for writing.
buffer: A valid buffer object. The OpenCL context associated with CLCommandQueueMBS 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.
EventWaitList: Optional, Specify events that need to complete before this particular command can be executed. The events specified in EventWaitList act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same.
outEvent: 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.

Lasterror is set.

The contents of the regions of a memory object mapped for writing (i.e. kMapWrite is set in map_flags argument to EnqueueMapBuffer or EnqueueMapImage) 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. MapFlags = kMapRead). 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.

Lasterror is set.

See also:

CLCommandQueueMBS.EnqueueMapBuffer(buffer as CLMemMBS, MapFlags as Integer, offset as Integer, size as Integer) as memoryblock

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
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.

BlockingMap: Optional, Indicates if the map operation is blocking or non-blocking. If BlockingMap is true, EnqueueMapBuffer does not return until the specified region in buffer can be mapped. If BlockingMap 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 EnqueueMapBuffer.
MapFlags: Is a bit-field and can be set to kMapRead to indicate that the region specified by (offset, size) in the buffer object is being mapped for reading, and/or kMapWrite to indicate that the region specified by (offset, size) in the buffer object is being mapped for writing.
buffer: A valid buffer object. The OpenCL context associated with CLCommandQueueMBS 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.
EventWaitList: Optional, Specify events that need to complete before this particular command can be executed. The events specified in EventWaitList act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same.
outEvent: 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.

Lasterror is set.

The contents of the regions of a memory object mapped for writing (i.e. kMapWrite is set in map_flags argument to EnqueueMapBuffer or EnqueueMapImage) 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. MapFlags = kMapRead). 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.

Lasterror is set.

See also:

CLCommandQueueMBS.EnqueueMapImage(image as CLMemMBS, BlockingMap as boolean, MapFlags as Integer, sourceOriginX as Integer, sourceOriginY as Integer, sourceOriginZ as Integer, RegionWidth as Integer, RegionHeight as Integer, RegionDepth as Integer, byref RowPitch as Integer, byref SlicePitch as Integer, EventWaitList() as CLEventMBS, byref outEvent as CLEventMBS) as memoryblock

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
Enqueues a command to map a region of an image object into the host address space and returns a pointer to this mapped region.

image: A valid image object. The OpenCL context associated with CLCommandQueueMBS and image must be the same.

BlockingMap: Optional, Indicates if the map operation is blocking or non-blocking. If BlockingMap is true, EnqueueMapImage does not return until the specified region in image can be mapped. If BlockingMap is false i.e. map operation is non-blocking, the pointer to the mapped region returned by EnqueueMapImage 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 EnqueueMapImage.

MapFlags: Is a bit-field and can be set to kMapRead to indicate that the region specified by (origin, region) in the image object is being mapped for reading, and/or kMapWrite to indicate that the region specified by (origin, region) in the image object is being mapped for writing.
origin, region: Define the (x, y, z) offset in pixels and (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 z value given by originZ must be 0 and the depth value given by regionDepth must be 1.

RowPitch: Returns the scan-line pitch in bytes for the mapped region. This must be a non-nil value.
SlicePitch: Returns the size in bytes of each 2D slice for the mapped region. For a 2D image, zero is returned if this argument is not nil. For a 3D image, image_slice_pitch must be a non-nil value.

EventWaitList: Optional, Specify events that need to complete before EnqueueMapImage can be executed. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and CLCommandQueueMBS must be the same.

outEvent: Optional, 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 nil 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.

Lasterror is set.

If the buffer or image object is created with kMemoryUseHostPtr set in mem_flags, the following will be true:

The HostPtr specified in Constructor is guaranteed to contain the latest bits in the region being mapped when the EnqueueMapBuffer or EnqueueMapImage command has completed.
The pointer value returned by EnqueueMapBuffer or EnqueueMapImage will be derived from the HostPtr specified when the buffer or image object is created.
The contents of the regions of a memory object mapped for writing (i.e. kMapWrite is set in MapFlags argument to EnqueueMapBuffer or EnqueueMapImage) 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. MapFlags = kMapRead). 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.

See also:

CLCommandQueueMBS.EnqueueMapImage(image as CLMemMBS, MapFlags as Integer, sourceOriginX as Integer, sourceOriginY as Integer, sourceOriginZ as Integer, RegionWidth as Integer, RegionHeight as Integer, RegionDepth as Integer, byref RowPitch as Integer, byref SlicePitch as Integer) as memoryblock

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
Enqueues a command to map a region of an image object into the host address space and returns a pointer to this mapped region.

image: A valid image object. The OpenCL context associated with CLCommandQueueMBS and image must be the same.

BlockingMap: Optional, Indicates if the map operation is blocking or non-blocking. If BlockingMap is true, EnqueueMapImage does not return until the specified region in image can be mapped. If BlockingMap is false i.e. map operation is non-blocking, the pointer to the mapped region returned by EnqueueMapImage 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 EnqueueMapImage.

MapFlags: Is a bit-field and can be set to kMapRead to indicate that the region specified by (origin, region) in the image object is being mapped for reading, and/or kMapWrite to indicate that the region specified by (origin, region) in the image object is being mapped for writing.
origin, region: Define the (x, y, z) offset in pixels and (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 z value given by originZ must be 0 and the depth value given by regionDepth must be 1.

RowPitch: Returns the scan-line pitch in bytes for the mapped region. This must be a non-nil value.
SlicePitch: Returns the size in bytes of each 2D slice for the mapped region. For a 2D image, zero is returned if this argument is not nil. For a 3D image, image_slice_pitch must be a non-nil value.

EventWaitList: Optional, Specify events that need to complete before EnqueueMapImage can be executed. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and CLCommandQueueMBS must be the same.

outEvent: Optional, 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 nil 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.

Lasterror is set.

If the buffer or image object is created with kMemoryUseHostPtr set in mem_flags, the following will be true:

The HostPtr specified in Constructor is guaranteed to contain the latest bits in the region being mapped when the EnqueueMapBuffer or EnqueueMapImage command has completed.
The pointer value returned by EnqueueMapBuffer or EnqueueMapImage will be derived from the HostPtr specified when the buffer or image object is created.
The contents of the regions of a memory object mapped for writing (i.e. kMapWrite is set in MapFlags argument to EnqueueMapBuffer or EnqueueMapImage) 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. MapFlags = kMapRead). 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.

See also:

CLCommandQueueMBS.EnqueueMarker(byref outEvent as CLEventMBS)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
Enqueues a marker command.

Enqueues a marker command to the 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.

Lasterror is set.

CLCommandQueueMBS.EnqueueNativeKernel(FunctionPtr as ptr, args as memoryblock, argsSize as Integer, NumberOfMemoryObjects as Integer, MemList as memoryblock, ArgsMemoryLocations as memoryblock)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
Enqueues a command to execute a native C/C++ function not compiled using the OpenCL compiler.

First a warning: Don't use this with Xojo methods. You can point to a function written in C which you made thread safe.

self: A valid command-queue. A native user function can only be executed on a command-queue created on a device that has kExceNativeKernel capability set in ExecutionCapabilities property.

FunctionPtr: A pointer to a host-callable user function.

args: A pointer to the args list that FunctionPtr should be called with.
argsSize: The size in bytes of the args list that args points to.

The data pointed to by args and argsSize bytes in size will be copied and a pointer to this copied region will be passed to FunctionPtr. The copy needs to be done because the memory objects (CLMemMBS.handle values) that args may contain need to be modified and replaced by appropriate pointers to global memory. When EnqueueNativeKernel returns, the memory region pointed to by args can be reused by the application.

NumberOfMemoryObjects: The number of buffer objects that are passed in args.

MemList: A list of valid buffer objects, if NumberOfMemoryObjects is greater than 0. The buffer object values specified in MemList are memory object handles (CLMemMBS.handle values) or nil.

ArgsMemoryLocations: A pointer to appropriate locations that args points to where memory object handles (CLMemMBS.handle values) are stored. Before the user function is executed, the memory object handles are replaced by pointers to global memory.

EventWaitList: Optionally, Specify events that need to complete before this particular command can be executed. 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.

outEvent: Optionally, Returns an event object that identifies this particular kernel execution instance.

The data pointed to by args and argsSize bytes in size will be copied and a pointer to this copied region will be passed to FunctionPtr. The copy needs to be done because the memory objects (CLMemMBS.handle values) that args may contain need to be modified and replaced by appropriate pointers to global memory. When EnqueueNativeKernel returns, the memory region pointed to by args can be reused by the application.

Lasterror is set.

See also:

CLCommandQueueMBS.EnqueueNativeKernel(FunctionPtr as ptr, args as memoryblock, argsSize as Integer, NumberOfMemoryObjects as Integer, MemList as memoryblock, ArgsMemoryLocations as memoryblock, EventWaitList() as CLEventMBS, byref outEvent as CLEventMBS)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
Enqueues a command to execute a native C/C++ function not compiled using the OpenCL compiler.

First a warning: Don't use this with Xojo methods. You can point to a function written in C which you made thread safe.

self: A valid command-queue. A native user function can only be executed on a command-queue created on a device that has kExceNativeKernel capability set in ExecutionCapabilities property.

FunctionPtr: A pointer to a host-callable user function.

args: A pointer to the args list that FunctionPtr should be called with.
argsSize: The size in bytes of the args list that args points to.

The data pointed to by args and argsSize bytes in size will be copied and a pointer to this copied region will be passed to FunctionPtr. The copy needs to be done because the memory objects (CLMemMBS.handle values) that args may contain need to be modified and replaced by appropriate pointers to global memory. When EnqueueNativeKernel returns, the memory region pointed to by args can be reused by the application.

NumberOfMemoryObjects: The number of buffer objects that are passed in args.

MemList: A list of valid buffer objects, if NumberOfMemoryObjects is greater than 0. The buffer object values specified in MemList are memory object handles (CLMemMBS.handle values) or nil.

ArgsMemoryLocations: A pointer to appropriate locations that args points to where memory object handles (CLMemMBS.handle values) are stored. Before the user function is executed, the memory object handles are replaced by pointers to global memory.

EventWaitList: Optionally, Specify events that need to complete before this particular command can be executed. 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.

outEvent: Optionally, Returns an event object that identifies this particular kernel execution instance.

The data pointed to by args and argsSize bytes in size will be copied and a pointer to this copied region will be passed to FunctionPtr. The copy needs to be done because the memory objects (CLMemMBS.handle values) that args may contain need to be modified and replaced by appropriate pointers to global memory. When EnqueueNativeKernel returns, the memory region pointed to by args can be reused by the application.

Lasterror is set.

See also:

CLCommandQueueMBS.EnqueueNDRangeKernel(kernel as CLKernelMBS, GlobalWorkSize as Integer, LocalWorkSize as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
Enqueues a command to execute a kernel on a device.

kernel: A valid kernel object. The OpenCL context associated with kernel and command_queue must be the same.
GlobalWorkSize: The number of global work-items.
LocalWorkSize: The number of work-items that make up a work-group (also referred to as the size of the work-group) that will execute the kernel specified by kernel.

The work-group size to be used for kernel can also be specified in the program source using the __attribute__((reqd_work_group_size(X, Y, Z)))qualifier. In this case the size of work group specified by local_work_size must match the value specified by the reqd_work_group_size __attribute__ qualifier.

EventWaitList: Optional, Specify events that need to complete before this particular command can be executed. If EventWaitList is empty or not passed, then this particular command does not wait on any event to complete. The events specified in EventWaitList act as synchronization points. The context associated with events in EventWaitList and CLCommandQueueMBS must be the same.
outEvent: Optional, Returns an event object that identifies this particular kernel execution instance. Event objects are unique and can be used to identify a particular kernel execution instance later on.

Work-group instances are executed in parallel across multiple compute units or concurrently on the same compute unit.

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 GlobalWorkSize 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 LocalWorkSize. The starting local ID is always (0, 0, ... 0).

Lasterror is set.

See also:

Some examples using this method:

CLCommandQueueMBS.EnqueueNDRangeKernel(kernel as CLKernelMBS, GlobalWorkSize as Integer, LocalWorkSize as Integer, EventWaitList() as CLEventMBS, byref outEvent as CLEventMBS)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
Enqueues a command to execute a kernel on a device.

kernel: A valid kernel object. The OpenCL context associated with kernel and command_queue must be the same.
GlobalWorkSize: The number of global work-items.
LocalWorkSize: The number of work-items that make up a work-group (also referred to as the size of the work-group) that will execute the kernel specified by kernel.

The work-group size to be used for kernel can also be specified in the program source using the __attribute__((reqd_work_group_size(X, Y, Z)))qualifier. In this case the size of work group specified by local_work_size must match the value specified by the reqd_work_group_size __attribute__ qualifier.

EventWaitList: Optional, Specify events that need to complete before this particular command can be executed. If EventWaitList is empty or not passed, then this particular command does not wait on any event to complete. The events specified in EventWaitList act as synchronization points. The context associated with events in EventWaitList and CLCommandQueueMBS must be the same.
outEvent: Optional, Returns an event object that identifies this particular kernel execution instance. Event objects are unique and can be used to identify a particular kernel execution instance later on.

Work-group instances are executed in parallel across multiple compute units or concurrently on the same compute unit.

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 GlobalWorkSize 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 LocalWorkSize. The starting local ID is always (0, 0, ... 0).

Lasterror is set.

See also:

CLCommandQueueMBS.EnqueueReadBuffer(buffer as CLMemMBS, BlockingRead as boolean, offset as Integer, size as Integer, mem as Memoryblock, EventWaitList() as CLEventMBS, byref outEvent as CLEventMBS)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method OpenCL MBS MacFrameworks Plugin 11.1 ✅ Yes ❌ No ❌ No ✅ Yes All
Enqueue commands to read from a buffer object to host memory.

buffer: Refers to a valid buffer object.
BlockingRead: Optional, Indicates if the read operations are blocking or non-blocking. If BlockingRead is true i.e. the read command is blocking, clEnqueueReadBuffer does not return until the buffer data has been read and copied into memory pointed to by ptr.

If BlockingRead is false i.e. the read command is non-blocking, EnqueueReadBuffer 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.

offset: The offset in bytes in the buffer object to read from.
size: The size in bytes of data being read.
mem: The pointer to buffer in host memory where data is to be read into.

EventWaitList: Optional, specifies events that need to complete before this particular command can be executed. If EventWaitList is empty or not passed, then this particular command does not wait on any event to complete. The events specified in EventWaitList act as synchronization points. The context associated with events in EventWaitList and command_queue must be the same.

outEvent: Optional, 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.

Calling EnqueueReadBuffer to read a region of the buffer object with the ptr argument value set to mem + offset, where mem is a pointer to the memory region specified when the buffer object being read is created with kMemoryUseHostPtr, 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

Lasterror is set.

See also:

Some examples using this method:

Next items

The items on this page are in the following plugins: MBS MacFrameworks Plugin.


The biggest plugin in space...