runtime.rst

OpenCL Platform/Runtime Documentation

Version Queries

Error Reporting

Base class for all PyOpenCL exceptions.

Constants

Platforms, Devices and Contexts

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 instances of this class may be compared using ==" and "!=".

Create a new context. properties is a list of key-value tuples, where each key must be one of :class:`context_properties`. At most one of devices and dev_type may be not None, where devices is a list of :class:`Device` instances, and dev_type is one of the :class:`device_type` constants. If neither is specified, a context with a dev_type of :attr:`device_type.DEFAULT` is created.

Note

Calling the constructor with no arguments will fail for recent CL drivers that support the OpenCL ICD. If you want similar, just-give-me-a-context-already behavior, we recommend :func:`create_some_context`. See, e.g. this explanation by AMD.

Note

For :attr:`context_properties.CL_GL_CONTEXT_KHR`, :attr:`context_properties.CL_EGL_DISPLAY_KHR`, :attr:`context_properties.CL_GLX_DISPLAY_KHR`, :attr:`context_properties.CL_WGL_HDC_KHR`, and :attr:`context_properties.CL_CGL_SHAREGROUP_KHR` :attr:`context_properties.CL_CGL_SHAREGROUP_APPLE` the value in the key-value pair is a PyOpenGL context or display instance.

Instances of this class are hashable, and two instances of this class may be compared using "==" and "!=". (Hashability was added in version 2011.2.)

Command Queues and Events

Create a new command queue. properties is a bit field consisting of :class:`command_queue_properties` values.

if device is None, one of the devices in context is chosen in an implementation-defined manner.

Instances of this class are hashable, and two instances of this class may be compared using "==" and "!=". (Hashability was added in version 2011.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.)

A subclass of :class:`Event`. Only available with OpenCL 1.1 and newer.

Transfers between host and device return events of this type. They hold a reference to the host-side buffer and wait for the transfer to complete when they are freed. Therefore, they can safely release the reference to the object they're guarding upon destruction.

A subclass of :class:`Event`.

Memory

Instances of this class are hashable, and two instances of this class may be compared using "==" and "!=". (Hashability was added in version 2011.2.)

Buffers

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` is a subclass of :class:`MemoryObject`.

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

Image Formats

Images

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` is a subclass of :class:`MemoryObject`.

Note

If you want to load images from :mod:`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.

Instances of this class are hashable, and two instances of this class may be compared using "==" and "!=". (Hashability was added in version 2011.2.)

Transfers

Mapping Memory into Host Address Space

Samplers

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

Instances of this class are hashable, and two instances of this class may be compared using "==" and "!=". (Hashability was added in version 2011.2.)

Programs and Kernels

binaries must contain one binary for each entry in devices.

Instances of this class are hashable, and two instances of this class may be compared using "==" and "!=". (Hashability was added in version 2011.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.)

A helper class to pass __local memory arguments to kernels.

GL Interoperability

Functionality in this section is only available when PyOpenCL is compiled with GL support. See :func:`have_gl`.

:class:`GLBuffer` is a subclass of :class:`MemoryObject`.

:class:`GLRenderBuffer` is a subclass of :class:`MemoryObject`.

dims is either 2 or 3. :class:`GLTexture` is a subclass of :class:`Image`.