# OpenCL Runtime: Memory

class pyopencl.MemoryObject
  info

    Lower case versions of the `mem_info` constants may be used as attributes on instances of this class to directly query info attributes.

  hostbuf
  get_info(param)

    See `mem_info` for values of param.

  release()
  get_host_array(shape, dtype, order='C')

    Return the memory object’s associated host memory area as a `numpy.ndarray` of the given shape, dtype and order.

  from_int_ptr(int_ptr_value: int, retain: bool = True) → object

    (static method) Return a new Python object referencing the C-level `cl_mem` object at the location pointed to by int_ptr_value. The relevant `clRetain*` function will be called if retain is True.If the previous owner of the object will not release the reference, retain should be set to False, to effectively transfer ownership to `pyopencl`.

    Added in version 2013.2.

    Changed in version 2016.1: retain added.

  int_ptr

    Return an integer corresponding to the pointer value of the underlying `cl_mem`. Use `from_int_ptr()` to turn back into a Python object.

    Added in version 2013.2.

  Instances of this class are hashable, and two instances of this class may be compared using “==” and “!=”. (Hashability was added in version 2011.2.) Two objects are considered the same if the underlying OpenCL object is the same, as established by C pointer equality.

## Memory Migration

pyopencl.enqueue_migrate_mem_objects(queue, mem_objects, flags=0, wait_for=None)
  Parameters:

    flags – from `mem_migration_flags`

  Added in version 2011.2.

  Only available with CL 1.2.

## Buffer

class pyopencl.Buffer(context, flags, size=0, hostbuf=None)

  Create a `Buffer`. See `mem_flags` for values of flags. If hostbuf is specified, size defaults to the size of the specified buffer if it is passed as zero.

  `Buffer` inherits from `MemoryObject`.

  Note

  Python also defines a type of buffer object, and PyOpenCL interacts with those, too, as the host-side target of `enqueue_copy()`. Make sure to always be clear on whether a `Buffer` or a Python buffer object is needed.

  Note that actual memory allocation in OpenCL may be deferred. Buffers are attached to a `Context` and are only moved to a device once the buffer is used on that device. That is also the point when out-of-memory errors will occur. If you’d like to be sure that there’s enough memory for your allocation, either use `enqueue_migrate_mem_objects()` (if available) or simply perform a small transfer to the buffer. See also `pyopencl.tools.ImmediateAllocator`.

  get_sub_region(origin, size, flags=0)

    Only available in OpenCL 1.1 and newer.

  __getitem__(slc)

    slc is a `slice` object indicating from which byte index range a sub-buffer is to be created. The flags argument of `get_sub_region()` is set to the same flags with which self was created.

pyopencl.enqueue_fill_buffer(queue, mem, pattern, offset, size, wait_for=None)
  Parameters:

    - mem – the on device `Buffer`

    - pattern – a buffer object (likely a `numpy.ndarray`, eg. `np.uint32(0)`). The memory associated with pattern can be reused or freed once the function completes.

    - size – The size in bytes of the region to be filled. Must be a multiple of the size of the pattern.

    - offset – The location in bytes of the region being filled in mem. Must be a multiple of the size of the pattern.

  Fills a buffer with the provided pattern

  Returns a new `pyopencl.Event`. wait_for may either be None or a list of `pyopencl.Event` instances for whose completion this command waits before starting execution.

  Only available with CL 1.2.

  Added in version 2011.2.

## Shared Virtual Memory (SVM)

Shared virtual memory allows the host and the compute device to share address space, so that pointers on the host and on the device may have the same meaning. In addition, it allows the same memory to be accessed by both the host and the device. Coarse-grain SVM requires that buffers be mapped before being accessed on the host, fine-grain SVM does away with that requirement.

Warning

Compared to `Buffer`s, SVM brings with it a new concern: the synchronization of memory deallocation. Unlike other objects in OpenCL, SVM is represented by a plain (C-language) pointer and thus has no ability for reference counting.

As a result, it is perfectly legal to allocate a `Buffer`, enqueue an operation on it, and release the buffer, without worrying about whether the operation has completed. The OpenCL implementation will keep the buffer alive until the operation has completed. This is not the case with SVM: Unless otherwise specified, memory deallocation is performed immediately when requested, and so SVM will be deallocated whenever the Python garbage collector sees fit, even if the operation has not completed, immediately leading to undefined behavior (i.e., typically, memory corruption and, before too long, a crash).

Version 2022.2 of PyOpenCL offers substantially improved tools for dealing with this. In particular, all means for allocating SVM allow specifying a `CommandQueue`, so that deallocation is enqueued and performed after previously-enqueued operations have completed.

SVM requires OpenCL 2.0.

### Opaque and “Wrapped-`numpy`” Styles of Referencing SVM

When trying to pass SVM pointers to functionality in `pyopencl`, two styles are supported:

- First, the opaque style. This style most closely resembles `Buffer`-based allocation available in OpenCL 1.x. SVM pointers are held in opaque “handle” objects such as `SVMAllocation`.

- Second, the wrapped-`numpy` style. In this case, a `numpy.ndarray` (or another object implementing the `Python buffer protocol`) serves as the reference to an area of SVM. This style permits using memory areas with `pyopencl`’s SVM interfaces even if they were allocated outside of `pyopencl`.

  Since passing a `numpy.ndarray` (or another type of object obeying the buffer interface) already has existing semantics in most settings in `pyopencl` (such as when passing arguments to a kernel or calling `enqueue_copy()`), there exists a wrapper object, `SVM`, that may be “wrapped around” these objects to mark them as SVM.

The commonality between the two styles is that both ultimately implement the `SVMPointer` interface, which `pyopencl` uses to obtain the actual SVM pointer.

Note that it is easily possible to obtain a `numpy.ndarray` view of SVM areas held in the opaque style, see `SVMPointer.buf`, permitting transitions from opaque to wrapped-`numpy` style. The opposite transition (from wrapped-`numpy` to opaque) is not necessarily straightforward, as it would require “fishing” the opaque SVM handle out of a chain of `numpy.ndarray.base` attributes (or similar, depending on the actual object serving as the main SVM reference).

See Helper functions for numpy-based SVM allocation for helper functions that ease setting up the wrapped-`numpy` structure.

Wrapped-`numpy` SVM tends to be a good fit for fine-grain SVM because of the ease of direct host-side access, but the creation of the nested structure that makes this possible is associated with a certain amount of cost.

By comparison, opaque SVM access tends to be a good fit for coarse-grain SVM, because direct host access is not possible without mapping the array anyway, and it has lower setup cost. It is of course entirely possible to use opaque SVM access with fine-grain SVM.

Changed in version 2022.2: This version adds the opaque style of SVM access.

### Using SVM with Arrays

While all types of SVM can be used as the memory backing `pyopencl.array.Array` objects, ensuring that new arrays returned by array operations (e.g. arithmetic) also use SVM is easiest to accomplish by passing an `SVMAllocator` (or `SVMPool`) as the allocator parameter in functions returning new arrays.

### SVM Pointers, Allocations, and Maps

class pyopencl.SVMPointer

  A base class for things that can be passed to functions that allow an SVM pointer, e.g. kernel enqueues and memory copies.

  Objects of this type cannot currently be directly created or implemented in Python. To obtain objects implementing this type, consider its subtypes `SVMAllocation` and `SVM`.

  property svm_ptr

    Gives the SVM pointer as an `int`.

  property size

    An `int` denoting the size in bytes, or None, if the size of the SVM pointed to is not known.

    Most objects of this type (e.g. instances of `SVMAllocation` and `SVM` know their size, so that, for example `enqueue_copy` will automatically copy an entire `SVMAllocation` when a size is not explicitly specified.

  map(queue: CommandQueue, *, flags: int, is_blocking: bool = True, wait_for: Sequence[Event] | None = None, size: Event | None = None) → SVMMap
    Parameters:

      - is_blocking – If False, subsequent code must wait on `SVMMap.event` in the returned object before accessing the mapped memory.

      - flags – a combination of `pyopencl.map_flags`.

      - size – The size of the map in bytes. If not provided, defaults to `size`.

    Returns a new `pyopencl.Event`. wait_for may either be None or a list of `pyopencl.Event` instances for whose completion this command waits before starting execution.

  map_ro(queue: CommandQueue, *, is_blocking: bool = True, wait_for: Sequence[Event] | None = None, size: int | None = None) → SVMMap

    Like `map()`, but with flags set for a read-only map.

  map_rw(queue: CommandQueue, *, is_blocking: bool = True, wait_for: Sequence[Event] | None = None, size: int | None = None) → SVMMap

    Like `map()`, but with flags set for a read-only map.

  as_buffer(ctx: Context, *, flags: int | None = None, size: int | None = None) → Buffer
    Parameters:

      - ctx – a `Context`

      - flags – a combination of `pyopencl.map_flags`, defaults to read-write.

      - size – The size of the map in bytes. If not provided, defaults to `size`.

    Returns:

      a `Buffer` corresponding to self.

    The memory referred to by this object must not be freed before the returned `Buffer` is released.

  property buf

    An opaque object implementing the `Python buffer protocol`. It exposes the pointed-to memory as a one-dimensional buffer of bytes, with the size matching `size`.

    No guarantee is provided that two references to this attribute result in the same object.

class pyopencl.SVMAllocation(*args, **kwargs)

  Is a `SVMPointer`.

  Added in version 2016.2.

  __init__(self, context: pyopencl._cl.Context, size: int, alignment: int, flags: int, queue: pyopencl._cl.CommandQueue | None = None) → None
    Parameters:

      - flags – See `svm_mem_flags`.

      - queue –

        If not specified, the allocation will be freed eagerly, irrespective of whether pending/enqueued operations are still using this memory.

        If specified, deallocation of the memory will be enqueued with the given queue, and will only be performed after previously-enqueue operations in the queue have completed.

        It is an error to specify an out-of-order queue.

        Warning

        Not specifying a queue will typically lead to undesired behavior, including crashes and memory corruption. See the warning in Shared Virtual Memory (SVM).

  enqueue_release(self, queue: pyopencl._cl.CommandQueue | None = None, wait_for: object | None = None) → pyopencl._cl.Event
    Returns:

      a `pyopencl.Event`

    Returns a new `pyopencl.Event`. wait_for may either be None or a list of `pyopencl.Event` instances for whose completion this command waits before starting execution.

    Enqueue the release of this allocation into queue. If queue is not specified, enqueue the deallocation into the queue provided at allocation time or via `bind_to_queue`.

  bind_to_queue(self, queue: pyopencl._cl.CommandQueue) → None

    Change the queue used for implicit enqueue of deallocation to queue. Sufficient synchronization is ensured by enqueuing a marker into the old queue and waiting on this marker in the new queue.

  unbind_from_queue(self) → None

    Configure the allocation to no longer implicitly enqueue memory allocation. If such a queue was previously provided, `finish()` is automatically called on it.

class pyopencl.SVM(*args, **kwargs)

  Tags an object exhibiting the Python buffer interface (such as a `numpy.ndarray`) as referring to shared virtual memory.

  Is a `SVMPointer`, hence objects of this type may be passed to kernel calls and `enqueue_copy()`, and all methods declared there are also available there. Note that `map()` differs slightly from `SVMPointer.map()`.

  Depending on the features of the OpenCL implementation, the following types of objects may be passed to/wrapped in this type:

  - fine-grain shared memory as returned by (e.g.) `fsvm_empty()`, if the implementation supports fine-grained shared virtual memory. This memory may directly be passed to a kernel:

        ary = cl.fsvm_empty(ctx, 1000, np.float32)
        assert isinstance(ary, np.ndarray)

        prg.twice(queue, ary.shape, None, cl.SVM(ary))
        queue.finish() # synchronize
        print(ary) # access from host

    Observe how mapping (as needed in coarse-grain SVM) is no longer necessary.

  - any `numpy.ndarray` (or other Python object with a buffer interface) if the implementation supports fine-grained system shared virtual memory.

    This is how plain `numpy` arrays may directly be passed to a kernel:

        ary = np.zeros(1000, np.float32)
        prg.twice(queue, ary.shape, None, cl.SVM(ary))
        queue.finish() # synchronize
        print(ary) # access from host

  - coarse-grain shared memory as returned by (e.g.) `csvm_empty()` for any implementation of OpenCL 2.0.

    Note

    Applications making use of coarse-grain SVM may be better served by opaque-style SVM. See Opaque and “Wrapped-numpy” Styles of Referencing SVM.

    This is how coarse-grain SVM may be used from both host and device:

        svm_ary = cl.SVM(
            cl.csvm_empty(ctx, 1000, np.float32, alignment=64))
        assert isinstance(svm_ary.mem, np.ndarray)

        with svm_ary.map_rw(queue) as ary:
            ary.fill(17)  # use from host

        prg.twice(queue, svm_ary.mem.shape, None, svm_ary)

  Coarse-grain shared-memory must be mapped into host address space using `map()` before being accessed through the `numpy` interface.

  Note

  This object merely serves as a ‘tag’ that changes the behavior of functions to which it is passed. It has no special management relationship to the memory it tags. For example, it is permissible to grab a `numpy.ndarray` out of `SVM.mem` of one `SVM` instance and use the array to construct another. Neither of the tags need to be kept alive.

  Added in version 2016.2.

  mem

    The wrapped object.

  __init__(self, arg: object, /) → None
  map(queue, flags, is_blocking=True, wait_for=None)
    Parameters:

      - is_blocking – If False, subsequent code must wait on `SVMMap.event` in the returned object before accessing the mapped memory.

      - flags – a combination of `pyopencl.map_flags`.

    Returns:

      an `SVMMap` instance

    This differs from the inherited `SVMPointer.map` in that no size can be specified, and that `mem` is the exact array produced when the `SVMMap` is used as a context manager.

    Returns a new `pyopencl.Event`. wait_for may either be None or a list of `pyopencl.Event` instances for whose completion this command waits before starting execution.

  map_ro(queue, is_blocking=True, wait_for=None)

    Like `map()`, but with flags set for a read-only map.

  map_rw(queue, is_blocking=True, wait_for=None)

    Like `map()`, but with flags set for a read-only map.

class pyopencl.SVMMap(svm, array, queue, event)

  Returned by `SVMPointer.map()` and `SVM.map()`. This class may also be used as a context manager in a `with` statement. `release()` will be called upon exit from the `with` region. The value returned to the `as` part of the context manager is the mapped Python object (e.g. a `numpy` array).

  Added in version 2016.2.

  property event

    The `Event` returned when mapping the memory.

  release(queue=None, wait_for=None)
    Parameters:

      queue – a `pyopencl.CommandQueue`. Defaults to the one with which the map was created, if not specified.

    Returns:

      a `pyopencl.Event`

    Returns a new `pyopencl.Event`. wait_for may either be None or a list of `pyopencl.Event` instances for whose completion this command waits before starting execution.

### Helper functions for `numpy`-based SVM allocation

pyopencl.svm_empty(ctx, flags, shape, dtype, order='C', alignment=None, queue=None)

  Allocate an empty `numpy.ndarray` of the given shape, dtype and order. (See `numpy.empty()` for the meaning of these arguments.) The array will be allocated in shared virtual memory belonging to ctx.

  Parameters:

    - ctx – a `Context`

    - flags – a combination of flags from `svm_mem_flags`.

    - alignment – the number of bytes to which the beginning of the memory is aligned. Defaults to the `numpy.dtype.itemsize` of dtype.

  Returns:

    a `numpy.ndarray` whose `numpy.ndarray.base` attribute is a `SVMAllocation`.

  To pass the resulting array to an OpenCL kernel or `enqueue_copy()`, you will likely want to wrap the returned array in an `SVM` tag.

  Added in version 2016.2.

  Changed in version 2022.2: queue argument added.

pyopencl.svm_empty_like(ctx, flags, ary, alignment=None)

  Allocate an empty `numpy.ndarray` like the existing `numpy.ndarray` ary. The array will be allocated in shared virtual memory belonging to ctx.

  Parameters:

    - ctx – a `Context`

    - flags – a combination of flags from `svm_mem_flags`.

    - alignment – the number of bytes to which the beginning of the memory is aligned. Defaults to the `numpy.dtype.itemsize` of dtype.

  Returns:

    a `numpy.ndarray` whose `numpy.ndarray.base` attribute is a `SVMAllocation`.

  To pass the resulting array to an OpenCL kernel or `enqueue_copy()`, you will likely want to wrap the returned array in an `SVM` tag.

  Added in version 2016.2.

pyopencl.csvm_empty(ctx, shape, dtype, order='C', alignment=None)

  Like `svm_empty()`, but with flags set for a coarse-grain read-write buffer.

  Added in version 2016.2.

pyopencl.csvm_empty_like(ctx, ary, alignment=None)

  Like `svm_empty_like()`, but with flags set for a coarse-grain read-write buffer.

  Added in version 2016.2.

pyopencl.fsvm_empty(ctx, shape, dtype, order='C', alignment=None)

  Like `svm_empty()`, but with flags set for a fine-grain read-write buffer.

  Added in version 2016.2.

pyopencl.fsvm_empty_like(ctx, ary, alignment=None)

  Like `svm_empty_like()`, but with flags set for a fine-grain read-write buffer.

  Added in version 2016.2.

### Operations on SVM

(See also Transfers.)

pyopencl.enqueue_svm_memfill(queue, dest, pattern, byte_count=None, wait_for=None)

  Fill shared virtual memory with a pattern.

  Parameters:

    - dest – a Python buffer object, or any implementation of `SVMPointer`.

    - pattern – a Python buffer object (e.g. a `numpy.ndarray` with the fill pattern to be used.

    - byte_count – The size of the memory to be fill. Defaults to the entirety of dest.

  Returns a new `pyopencl.Event`. wait_for may either be None or a list of `pyopencl.Event` instances for whose completion this command waits before starting execution.

  Added in version 2016.2.

pyopencl.enqueue_svm_migratemem(queue, svms, flags, wait_for=None)
  Parameters:

    - svms – a collection of Python buffer objects (e.g. `numpy` arrays), or any implementation of `SVMPointer`.

    - flags – a combination of `mem_migration_flags`

  Returns a new `pyopencl.Event`. wait_for may either be None or a list of `pyopencl.Event` instances for whose completion this command waits before starting execution.

  Added in version 2016.2.

  This function requires OpenCL 2.1.

## Image

class pyopencl.ImageFormat(channel_order, channel_type)
  channel_order

    See `channel_order` for possible values.

  channel_data_type

    See `channel_type` for possible values.

  channel_count

    Added in version 0.91.5.

  dtype_size

    Added in version 0.91.5.

  itemsize

    Added in version 0.91.5.

  __repr__()

    Returns a `str` representation of the image format.

    Added in version 0.91.

  Instances of this class are hashable, and two instances of this class may be compared using “==” and “!=”. (Hashability was added in version 2011.2.) Two objects are considered the same if the underlying OpenCL object is the same, as established by C pointer equality.

  Changed in version 0.91: Constructor arguments added.

  Changed in version 2013.2: `ImageFormat` was made comparable and hashable

pyopencl.get_supported_image_formats(context, flags, image_type)

  See `mem_flags` for possible values of flags and `mem_object_type` for possible values of image_type.

class pyopencl.Image
Use :func:`create_image` to create images.

  Added in version 0.91.

  info

    Lower case versions of the `mem_info` and `image_info` constants may be used as attributes on instances of this class to directly query info attributes.

  shape

    Return the value of the shape constructor argument as a `tuple`.

  get_image_info(param)

    See `image_info` for values of param.

  release()

  Instances of this class are hashable, and two instances of this class may be compared using “==” and “!=”. (Hashability was added in version 2011.2.) Two objects are considered the same if the underlying OpenCL object is the same, as established by C pointer equality.

pyopencl.create_image(context, flags, format, shape=None, pitches=None, hostbuf=None, is_array=False, buffer=None) → Image

  See `mem_flags` for values of flags. shape is a 2- or 3-tuple. format is an instance of `ImageFormat`. pitches is a 1-tuple for 2D images and a 2-tuple for 3D images, indicating the distance in bytes from one scan line to the next, and from one 2D image slice to the next.

  If hostbuf is given and shape is None, then hostbuf.shape is used as the shape parameter.

  `Image` inherits from `MemoryObject`.

  Note

  If you want to load images from `numpy.ndarray` instances or read images back into them, be aware that OpenCL images expect the x dimension to vary fastest, whereas in the default (C) order of `numpy` arrays, the last index varies fastest. If your array is arranged in the wrong order in memory, there are two possible fixes for this:

  - Convert the array to Fortran (column-major) order using `numpy.asarray()`.

  - Pass ary.T.copy() to the image creation function.

  Added in version 2024.3.

pyopencl.image_from_array(ctx, ary, num_channels=None, mode='r', norm_int=False)

  Build a 2D or 3D `Image` from the `numpy.ndarray` ary. If num_channels is greater than one, the last dimension of ary must be identical to num_channels. ary must be in C order. If num_channels is not given, it defaults to 1 for scalar types and the number of entries for Vector Types.

  The `ImageFormat` is chosen as the first num_channels components of “RGBA”.

  Parameters:

    mode – “r” or “w” for read/write

  Note

  When reading from the image object, the indices passed to `read_imagef` are in the reverse order from what they would be when accessing ary from Python.

  If norm_int is True, then the integer values are normalized to a floating point scale of 0..1 when read.

  Added in version 2011.2.

pyopencl.enqueue_fill_image(queue, mem, color, origin, region, wait_for=None)
  Parameters:

    color – a buffer object (likely a `numpy.ndarray`)

  Returns a new `pyopencl.Event`. wait_for may either be None or a list of `pyopencl.Event` instances for whose completion this command waits before starting execution.

  Only available with CL 1.2.

  Added in version 2011.2.

## Transfers

pyopencl.enqueue_copy(queue, dest, src, **kwargs)

  Copy from `Image`, `Buffer` or the host to `Image`, `Buffer` or the host. (Note: host-to-host copies are unsupported.)

  The following keyword arguments are available:

  Parameters:

    - wait_for – (optional, default empty)

    - is_blocking – Wait for completion. Defaults to True. (Available on any copy involving host memory)

  Returns:

    A `NannyEvent` if the transfer involved a host-side buffer, otherwise an `Event`.

  Note

  Be aware that the deletion of the `NannyEvent` that is returned by the function if the transfer involved a host-side buffer will block until the transfer is complete, so be sure to keep a reference to this `Event` until the transfer has completed.

  Note

  Two types of ‘buffer’ occur in the arguments to this function, `Buffer` and ‘host-side buffers’. The latter are defined by Python and commonly called buffer objects. `numpy` arrays are a very common example. Make sure to always be clear on whether a `Buffer` or a Python buffer object is needed.

  Transfer `Buffer` ↔ host

  Parameters:

    - src_offset –

      offset in bytes (optional)

      May only be nonzero if applied on the device side.

    - dst_offset –

      offset in bytes (optional)

      May only be nonzero if applied on the device side.

  Note

  The size of the transfer is controlled by the size of the of the host-side buffer. If the host-side buffer is a `numpy.ndarray`, you can control the transfer size by transferring into a smaller ‘view’ of the target array, like this:

      cl.enqueue_copy(queue, large_dest_numpy_array[:15], src_buffer)

  Transfer `Buffer` ↔ `Buffer`

  Parameters:

    - byte_count – (optional) If not specified, defaults to the size of the source in versions 2012.x and earlier, and to the minimum of the size of the source and target from 2013.1 on.

    - src_offset – (optional)

    - dst_offset – (optional)

  Rectangular `Buffer` ↔ host transfers (CL 1.1 and newer)

  Parameters:

    - buffer_origin – `tuple` of `int` of length three or shorter. (mandatory)

    - host_origin – `tuple` of `int` of length three or shorter. (mandatory)

    - region – `tuple` of `int` of length three or shorter. (mandatory)

    - buffer_pitches – `tuple` of `int` of length two or shorter. (optional, “tightly-packed” if unspecified)

    - host_pitches – `tuple` of `int` of length two or shorter. (optional, “tightly-packed” if unspecified)

  Rectangular `Buffer` ↔ `Buffer` transfers (CL 1.1 and newer)

  Parameters:

    - src_origin – `tuple` of `int` of length three or shorter. (mandatory)

    - dst_origin – `tuple` of `int` of length three or shorter. (mandatory)

    - region – `tuple` of `int` of length three or shorter. (mandatory)

    - src_pitches – `tuple` of `int` of length two or shorter. (optional, “tightly-packed” if unspecified)

    - dst_pitches – `tuple` of `int` of length two or shorter. (optional, “tightly-packed” if unspecified)

  Transfer `Image` ↔ host

  Parameters:

    - origin – `tuple` of `int` of length three or shorter. (mandatory)

    - region – `tuple` of `int` of length three or shorter. (mandatory)

    - pitches – `tuple` of `int` of length two or shorter. (optional)

  Transfer `Buffer` ↔ `Image`

  Parameters:

    - offset – offset in buffer (mandatory)

    - origin – `tuple` of `int` of length three or shorter. (mandatory)

    - region – `tuple` of `int` of length three or shorter. (mandatory)

  Transfer `Image` ↔ `Image`

  Parameters:

    - src_origin – `tuple` of `int` of length three or shorter. (mandatory)

    - dest_origin – `tuple` of `int` of length three or shorter. (mandatory)

    - region – `tuple` of `int` of length three or shorter. (mandatory)

  Transfer `SVMPointer`/host ↔ `SVMPointer`/host

  Parameters:

    byte_count – (optional) If not specified, defaults to the size of the source in versions 2012.x and earlier, and to the minimum of the size of the source and target from 2013.1 on.

  Returns a new `pyopencl.Event`. wait_for may either be None or a list of `pyopencl.Event` instances for whose completion this command waits before starting execution.

  Added in version 2011.1.

pyopencl.enqueue_fill(queue, dest, src, **kwargs)

  Added in version 2022.2.

pyopencl.enqueue_copy_buffer_p2p_amd(platform, queue, src, dest, size=None, wait_for=None)

  AMD extension to perform a peer-to-peer copy between two buffers on two different devices. The two devices must be in different contexts. The queue must be where the source buffer is located.

  Parameters:

    - platform – a `Platform` instance

    - queue – a `CommandQueue` instance

    - src – a `Buffer` instance

    - dest – a `Buffer` instance

    - size – the number of bytes to copy. If None, the minimum of the sizes of the two buffers is used.

  Returns a new `pyopencl.Event`. wait_for may either be None or a list of `pyopencl.Event` instances for whose completion this command waits before starting execution.

  Only available on AMD platforms.

  Added in version 2023.1.2.

## Mapping Memory into Host Address Space

class pyopencl.MemoryMap

  This class may also be used as a context manager in a `with` statement. The memory corresponding to this object will be unmapped when this object is deleted or `release()` is called.

  release(self, queue: pyopencl._cl.CommandQueue | None = None, wait_for: object | None = None) → pyopencl._cl.Event

pyopencl.enqueue_map_buffer(queue, buf, flags, offset, shape, dtype, order='C', strides=None, wait_for=None, is_blocking=True)

  wait_for may either be None or a list of `pyopencl.Event` instances for whose completion this command waits before starting execution. shape, dtype, and order have the same meaning as in `numpy.empty()`. See `map_flags` for possible values of flags. strides, if given, overrides order.

  Returns:

    a tuple (array, event). array is a `numpy.ndarray` representing the host side of the map. Its .base member contains a `MemoryMap`.

  Changed in version 2011.1: is_blocking now defaults to True.

  Changed in version 2013.1: order now defaults to “C”.

  Changed in version 2013.2: Added strides argument.

  Sample usage:

      mapped_buf = cl.enqueue_map_buffer(queue, buf, ...)
      with mapped_buf.base:
          # work with mapped_buf
          ...

      # memory will be unmapped here

pyopencl.enqueue_map_image(queue, buf, flags, origin, region, shape, dtype, order='C', strides=None, wait_for=None, is_blocking=True)

  wait_for may either be None or a list of `pyopencl.Event` instances for whose completion this command waits before starting execution. shape, dtype, and order have the same meaning as in `numpy.empty()`. See `map_flags` for possible values of flags. strides, if given, overrides order.

  Returns:

    a tuple (array, event). array is a `numpy.ndarray` representing the host side of the map. Its .base member contains a `MemoryMap`.

  Changed in version 2011.1: is_blocking now defaults to True.

  Changed in version 2013.1: order now defaults to “C”.

  Changed in version 2013.2: Added strides argument.

## Samplers

class pyopencl.Sampler
  __init__(context, normalized_coords, addressing_mode, filter_mode)

    normalized_coords is a `bool` indicating whether to use coordinates between 0 and 1 (True) or the texture’s natural pixel size (False). See `addressing_mode` and `filter_mode` for possible argument values.

    Also supports an alternate signature `(context, properties)`.

    Parameters:

      properties – a sequence of keys and values from `sampler_properties` as accepted by `clCreateSamplerWithProperties()` (see the OpenCL spec for details). The trailing 0 is added automatically and does not need to be included.

    This signature Requires OpenCL 2 or newer.

    Changed in version 2018.2: The properties-based signature was added.

  info

    Lower case versions of the `sampler_info` constants may be used as attributes on instances of this class to directly query info attributes.

  get_info(param)

    See `sampler_info` for values of param.

  from_int_ptr(int_ptr_value: int, retain: bool = True) → pyopencl._cl.Sampler

    (static method) Return a new Python object referencing the C-level `cl_sampler` object at the location pointed to by int_ptr_value. The relevant `clRetain*` function will be called if retain is True.If the previous owner of the object will not release the reference, retain should be set to False, to effectively transfer ownership to `pyopencl`.

    Added in version 2013.2.

    Changed in version 2016.1: retain added.

  int_ptr

    Return an integer corresponding to the pointer value of the underlying `cl_sampler`. Use `from_int_ptr()` to turn back into a Python object.

    Added in version 2013.2.

  Instances of this class are hashable, and two instances of this class may be compared using “==” and “!=”. (Hashability was added in version 2011.2.) Two objects are considered the same if the underlying OpenCL object is the same, as established by C pointer equality.

## Pipes

class pyopencl.Pipe(context, flags, packet_size, max_packets, properties=())

  See `mem_flags` for values of flags.

  Parameters:

    properties – a sequence of keys and values from `pipe_properties` as accepted by `clCreatePipe()`. The trailing 0 is added automatically and does not need to be included. (This argument must currently be empty.)

  This function requires OpenCL 2 or newer.

  Added in version 2020.3.

  Changed in version 2021.1.7: properties now defaults to an empty tuple.

  get_pipe_info(param)

    See `pipe_info` for values of param.

## Type aliases

class pyopencl._cl.Buffer

  See `pyopencl.Buffer`.

class pyopencl._cl.Image

  See `pyopencl.Image`.