runtime_memory.rst

OpenCL Runtime: Memory

|comparable|

Memory Migration

Buffer

Create a :class:`Buffer`. See :class:`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.

:class:`Buffer` inherits from :class:`MemoryObject`.

Note

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

Note that actual memory allocation in OpenCL may be deferred. Buffers are attached to a :class:`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 :func:`enqueue_migrate_mem_objects` (if available) or simply perform a small transfer to the buffer. See also :class:`pyopencl.tools.ImmediateAllocator`.

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.

SVM requires OpenCL 2.0.

Allocating SVM

Operations on SVM

(See also :ref:`mem-transfer`.)

SVM Allocation Holder

Image

|comparable|

See :class:`mem_flags` for values of flags. shape is a 2- or 3-tuple. format is an instance of :class:`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.

:class:`Image` inherits from :class:`MemoryObject`.

Note

If you want to load images from :class:`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 :mod:`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 :func:`numpy.asarray`.
• Pass ary.T.copy() to the image creation function.

|comparable|

Transfers

Mapping Memory into Host Address Space

Samplers

|comparable|