« back to all changes in this revision
Viewing changes to doc/source/runtime.rst
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Tomasz Rybak
- Date: 2010-05-31 19:29:00 UTC
- Revision ID: james.westby@ubuntu.com-20100531192900-ll7guuro37nntr4y
Tags: upstream-0.92~beta+git20100709
Import upstream version 0.92~beta+git20100709
- files added:
- bpl-subset
- doc
- doc/source
- examples
- pyopencl
- src
- src/wrapper
- test
added
removed
doc/source/runtime.rst
1
.. _reference-doc:
2
3
OpenCL Platform/Runtime Documentation
4
=====================================
5
6
Version Queries
7
---------------
8
9
.. module:: pyopencl
10
.. moduleauthor:: Andreas Kloeckner <inform@tiker.net>
11
12
.. data:: VERSION
13
14
Gives the numeric version of PyOpenCL as a variable-length tuple
15
of integers. Enables easy version checks such as
16
*VERSION >= (0, 93)*.
17
18
.. data:: VERSION_STATUS
19
20
A text string such as `"rc4"` or `"beta"` qualifying the status
21
of the release.
22
23
.. data:: VERSION_TEXT
24
25
The full release name (such as `"0.93rc4"`) in string form.
26
27
.. function:: get_cl_header_version()
28
29
Return a variable-length tuple of integers representing the
30
version of the OpenCL header against which PyOpenCL was
31
compiled.
32
33
.. versionadded:: 0.92
34
35
.. _errors:
36
37
Error Reporting
38
---------------
39
40
.. class:: Error
41
42
Base class for all PyOpenCL exceptions.
43
44
.. class:: MemoryError
45
46
.. class:: LogicError
47
48
.. class:: RuntimeError
49
50
Constants
51
---------
52
53
.. include:: constants.inc
54
55
Platforms, Devices and Contexts
56
-------------------------------
57
58
.. |comparable| replace:: Two instances of this class may be compared
59
using *"=="* and *"!="*.
60
.. |buf-iface| replace:: must implement the Python buffer interface.
61
(e.g. by being an :class:`numpy.ndarray`)
62
.. |explain-waitfor| replace:: *wait_for*
63
may either be *None* or a list of :class:`Event` instances for
64
whose completion this command waits before starting exeuction.
65
.. |std-enqueue-blurb| replace:: Returns a new :class:`Event`. |explain-waitfor|
66
67
.. function:: get_platforms()
68
69
Return a list of :class:`Platform` instances.
70
71
.. class:: Platform
72
73
.. attribute:: info
74
75
Lower case versions of the :class:`platform_info` constants
76
may be used as attributes on instances of this class
77
to directly query info attributes.
78
79
.. method:: get_info(param)
80
81
See :class:`platform_info` for values of *param*.
82
83
.. method:: get_devices(device_type=device_type.ALL)
84
85
Return a list of devices matching *device_type*.
86
See :class:`device_type` for values of *device_type*.
87
88
|comparable|
89
90
.. class:: Device
91
92
.. attribute:: info
93
94
Lower case versions of the :class:`device_info` constants
95
may be used as attributes on instances of this class
96
to directly query info attributes.
97
98
.. method:: get_info(param)
99
100
See :class:`device_info` for values of *param*.
101
102
Two instances of this class may be compared using *=="* and *"!="*.
103
104
.. class:: Context(devices=None, properties=None, dev_type=None)
105
106
Create a new context. *properties* is a list of key-value
107
tuples, where each key must be one of :class:`context_properties`.
108
At most one of *devices* and *dev_type* may be not `None`, where
109
*devices* is a list of :class:`Device` instances, and
110
*dev_type* is one of the :class:`device_type` constants.
111
If neither is specified, a context with a *dev_type* of
112
:attr:`device_type.DEFAULT` is created.
113
114
.. note::
115
116
Calling the constructor with no arguments will fail for recent
117
CL drivers that support the OpenCL ICD. If you want similar,
118
just-give-me-a-context-already behavior, we recommend
119
:func:`create_some_context`. See, e.g. this
120
`explanation by AMD <http://developer.amd.com/support/KnowledgeBase/Lists/KnowledgeBase/DispForm.aspx?ID=71>`_.
121
122
.. note::
123
124
For
125
:attr:`context_properties.CL_GL_CONTEXT_KHR`,
126
:attr:`context_properties.CL_EGL_DISPLAY_KHR`,
127
:attr:`context_properties.CL_GLX_DISPLAY_KHR`,
128
:attr:`context_properties.CL_WGL_HDC_KHR`, and
129
:attr:`context_properties.CL_CGL_SHAREGROUP_KHR`
130
the value in the key-value pair is a PyOpenGL context or display
131
instance.
132
133
.. versionchanged:: 0.91.2
134
Constructor arguments *dev_type* added.
135
136
.. attribute:: info
137
138
Lower case versions of the :class:`context_info` constants
139
may be used as attributes on instances of this class
140
to directly query info attributes.
141
142
.. method:: get_info(param)
143
144
See :class:`context_info` for values of *param*.
145
146
|comparable|
147
148
.. function:: create_some_context(interactive=True)
149
150
Create a :class:`Context` 'somehow'.
151
152
If multiple choices for platform and/or device exist, *interactive*
153
is True, and *sys.stdin.isatty()* is also True,
154
then the user is queried about which device should be chosen.
155
Otherwise, a device is chosen in an implementation-defined manner.
156
157
Command Queues and Events
158
-------------------------
159
160
.. class:: CommandQueue(context, device=None, properties=None)
161
162
Create a new command queue. *properties* is a bit field
163
consisting of :class:`command_queue_properties` values.
164
165
if *device* is None, one of the devices in *context* is chosen
166
in an implementation-defined manner.
167
168
.. attribute:: info
169
170
Lower case versions of the :class:`command_queue_info` constants
171
may be used as attributes on instances of this class
172
to directly query info attributes.
173
174
.. method:: get_info(param)
175
176
See :class:`command_queue_info` for values of *param*.
177
178
.. method:: set_property(prop, enable)
179
180
See :class:`command_queue_properties` for possible values of *prop*.
181
*enable* is a :class:`bool`.
182
183
Unavailable in OpenCL 1.1 and newer.
184
185
.. method:: flush()
186
.. method:: finish()
187
188
|comparable|
189
190
.. class:: Event
191
192
.. attribute:: info
193
194
Lower case versions of the :class:`event_info` constants
195
may be used as attributes on instances of this class
196
to directly query info attributes.
197
198
.. attribute:: profile.info
199
200
Lower case versions of the :class:`profiling_info` constants
201
may be used as attributes on the attribute `profile` of this
202
class to directly query profiling info.
203
204
For example, you may use *evt.profile.end* instead of
205
*evt.get_profiling_info(pyopencl.profiling_info.END)*.
206
207
.. method:: get_info(param)
208
209
See :class:`event_info` for values of *param*.
210
211
.. method:: get_profiling_info(param)
212
213
See :class:`profiling_info` for values of *param*.
214
See :attr:`profile` for an easier way of obtaining
215
the same information.
216
217
.. method:: wait()
218
219
|comparable|
220
221
.. function:: wait_for_events(events)
222
.. function:: enqueue_marker(queue)
223
224
Returns an :class:`Event`.
225
226
.. function:: enqueue_wait_for_events(queue, events)
227
228
Returns an :class:`Event`.
229
230
.. function:: enqueue_barrier(queue)
231
232
Enqueues a barrier operation. which ensures that all queued commands in
233
command_queue have finished execution. This command is a synchronization
234
point.
235
236
.. versionadded:: 0.91.5
237
238
.. class:: UserEvent(context)
239
240
A subclass of :class:`Event`. Only available with OpenCL 1.1 and newer.
241
242
.. versionadded:: 0.92
243
244
.. method:: set_status(status)
245
246
See :class:`command_execution_status` for possible values of *status*.
247
248
Memory
249
------
250
251
.. class:: MemoryObject
252
253
.. attribute:: info
254
255
Lower case versions of the :class:`mem_info` constants
256
may be used as attributes on instances of this class
257
to directly query info attributes.
258
259
.. method:: get_info(param)
260
261
See :class:`mem_info` for values of *param*.
262
263
.. attribute:: hostbuf
264
265
Contains the *hostbuf* parameter if the MemoryObject was constructed
266
with :attr:`mem_flags.USE_HOST_PTR`.
267
268
.. method:: release()
269
270
|comparable|
271
272
Buffers
273
^^^^^^^
274
275
.. class:: Buffer(context, flags, size=0, hostbuf=None)
276
277
Create a :class:`Buffer`.
278
See :class:`mem_flags` for values of *flags*.
279
If *hostbuf* is specified, *size* defaults to the size of
280
the specified buffer if it is passed as zero.
281
282
:class:`Buffer` is a subclass of :class:`MemoryObject`.
283
284
.. method:: get_sub_region(origin, size, flags=0)
285
286
.. method:: __getitem__(slc)
287
288
*slc* is a :class:`slice` object indicating from which byte index range
289
a sub-buffer is to be created. The *flags* argument of
290
:meth:`get_sub_region` is set to the same flags with which *self* was
291
created.
292
293
.. function:: enqueue_read_buffer(queue, mem, hostbuf, device_offset=0, wait_for=None, is_blocking=False)
294
295
|std-enqueue-blurb|
296
297
*hostbuf* |buf-iface|
298
299
.. function:: enqueue_write_buffer(queue, mem, hostbuf, device_offset=0, wait_for=None, is_blocking=False)
300
301
|std-enqueue-blurb|
302
303
*hostbuf* |buf-iface|
304
305
.. function:: enqueue_copy_buffer(queue, src, dst, byte_count=0, src_offset=0, dst_offset=0, wait_for=None)
306
307
If *byte_count* is passed as 0 (the default), the size of the
308
:class:`Buffer` *src* is used instead.
309
310
|std-enqueue-blurb|
311
312
.. versionadded:: 0.91.5
313
314
.. function:: enqueue_read_buffer_rect(queue, mem, hostbuf, buffer_origin, host_origin, region, buffer_pitches=None, host_pitches=None, wait_for=None, is_blocking=False)
315
316
The *origin* and *region* parameters are :class:`tuple` instances of length
317
three or shorter. The *pitches* parameters are :class:`tuple` instances of
318
length two or shorter, which may be zero to indicate 'tight packing'.
319
320
|std-enqueue-blurb|
321
322
*hostbuf* |buf-iface|
323
324
Only available in OpenCL 1.1 and newer.
325
326
.. versionadded:: 0.92
327
328
.. function:: enqueue_write_buffer_rect(queue, mem, hostbuf, buffer_origin, host_origin, region, buffer_pitches=None, host_pitches=None, wait_for=None, is_blocking=False)
329
330
The *origin* and *region* parameters are :class:`tuple` instances of length
331
three or shorter. The *pitches* parameters are :class:`tuple` instances of
332
length two or shorter, which may be zero to indicate 'tight packing'.
333
334
|std-enqueue-blurb|
335
336
*hostbuf* |buf-iface|
337
338
Only available in OpenCL 1.1 and newer.
339
340
.. versionadded:: 0.92
341
342
.. function:: enqueue_copy_buffer_rect(queue, src, dst, src_origin, dst_origin, region, src_pitches=None, dst_pitches=None, wait_for=None)
343
344
The *origin* and *region* parameters are :class:`tuple` instances of length
345
three or shorter. The *pitches* parameters are :class:`tuple` instances of
346
length two or shorter, which may be zero to indicate 'tight packing'.
347
348
|std-enqueue-blurb|
349
350
Only available in OpenCL 1.1 and newer.
351
352
.. versionadded:: 0.92
353
354
Image Formats
355
^^^^^^^^^^^^^
356
357
.. class:: ImageFormat([channel_order, channel_type])
358
359
.. versionchanged:: 0.91
360
Constructor arguments added.
361
362
.. attribute:: channel_order
363
364
See :class:`channel_order` for possible values.
365
366
.. attribute:: channel_data_type
367
368
See :class:`channel_type` for possible values.
369
370
.. attribute:: channel_count
371
372
.. versionadded:: 0.91.5
373
374
.. attribute:: dtype_size
375
376
.. versionadded:: 0.91.5
377
378
.. attribute:: itemsize
379
380
.. versionadded:: 0.91.5
381
382
.. method:: __repr__
383
384
Returns a :class:`str` representation of the image format.
385
386
.. versionadded:: 0.91
387
388
.. function:: get_supported_image_formats(context, flags, image_type)
389
390
See :class:`mem_flags` for possible values of *flags*
391
and :class:`mem_object_type` for possible values of *image_type*.
392
393
Images
394
^^^^^^
395
.. class:: Image(context, flags, format, shape=None, pitches=None, hostbuf=None)
396
397
*shape* is a 2- or 3-tuple.
398
399
If *hostbuf* is given and *shape* is `None`, then *hostbuf.shape* is
400
used as the *shape* parameter.
401
402
:class:`Image` is a subclass of :class:`MemoryObject`.
403
404
.. versionadded:: 0.91
405
406
.. attribute:: info
407
408
Lower case versions of the :class:`mem_info`
409
and :class:`image_info` constants
410
may be used as attributes on instances of this class
411
to directly query info attributes.
412
413
.. attribute:: shape
414
415
Return the value of the *shape* constructor argument as a :class:`tuple`.
416
417
.. method:: get_image_info(param)
418
419
See :class:`image_info` for values of *param*.
420
421
.. method:: release()
422
423
|comparable|
424
425
.. function:: enqueue_read_image(queue, mem, origin, region, hostbuf, row_pitch=0, slice_pitch=0, wait_for=None, is_blocking=False)
426
427
|std-enqueue-blurb|
428
429
.. versionchanged:: 0.91
430
*pitch* arguments defaults to zero, moved.
431
432
.. function:: enqueue_write_image(queue, mem, origin, region, hostbuf, row_pitch=0, slice_pitch=0, wait_for=None, is_blocking=False)
433
434
|std-enqueue-blurb|
435
436
.. versionchanged:: 0.91
437
*pitch* arguments defaults to zero, moved.
438
439
.. function:: enqueue_copy_image(queue, src, dest, src_origin, dest_origin, region, wait_for=None)
440
441
|std-enqueue-blurb|
442
443
.. function:: enqueue_copy_image_to_buffer(queue, src, dest, origin, region, offset, wait_for=None)
444
445
|std-enqueue-blurb|
446
447
.. function:: enqueue_copy_buffer_to_image(queue, src, dest, offset, origin, region, wait_for=None)
448
449
|std-enqueue-blurb|
450
451
Mapping Memory into Host Address Space
452
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
453
454
.. class:: MemoryMap
455
456
.. method:: release(queue=None, wait_for=None)
457
458
.. function:: enqueue_map_buffer(queue, buf, flags, offset, shape, dtype, order, wait_for=None, is_blocking=False)
459
460
|explain-waitfor|
461
*shape*, *dtype*, and *order* have the same meaning
462
as in :func:`numpy.empty`.
463
See :class:`map_flags` for possible values of *flags*.
464
465
:return: a tuple *(array, event)*. *array* is a
466
:class:`numpy.ndarray` representing the host side
467
of the map. Its *.base* member contains a
468
:class:`MemoryMap`.
469
470
.. function:: enqueue_map_image(queue, buf, flags, origin, region, shape, dtype, order, wait_for=None, is_blocking=False)
471
472
|explain-waitfor|
473
*shape*, *dtype*, and *order* have the same meaning
474
as in :func:`numpy.empty`.
475
See :class:`map_flags` for possible values of *flags*.
476
477
:return: a tuple *(array, event)*. *array* is a
478
:class:`numpy.ndarray` representing the host side
479
of the map. Its *.base* member contains a
480
:class:`MemoryMap`.
481
482
483
Samplers
484
^^^^^^^^
485
486
.. class:: Sampler(context, normalized_coords, addressing_mode, filter_mode)
487
488
*normalized_coords* is a :class:`bool` indicating whether
489
to use coordinates between 0 and 1 (*True*) or the texture's
490
natural pixel size (*False*).
491
See :class:`addressing_mode` and :class:`filter_mode` for possible
492
argument values.
493
494
.. attribute:: info
495
496
Lower case versions of the :class:`sampler_info` constants
497
may be used as attributes on instances of this class
498
to directly query info attributes.
499
500
.. method:: get_info(param)
501
502
See :class:`sampler_info` for values of *param*.
503
504
|comparable|
505
506
Programs and Kernels
507
--------------------
508
509
.. class:: Program(context, src)
510
Program(context, devices, binaries)
511
512
*binaries* must contain one binary for each entry in *devices*.
513
514
.. attribute:: info
515
516
Lower case versions of the :class:`program_info` constants
517
may be used as attributes on instances of this class
518
to directly query info attributes.
519
520
.. method:: get_info(param)
521
522
See :class:`program_info` for values of *param*.
523
524
.. method:: get_build_info(device, param)
525
526
See :class:`program_build_info` for values of *param*.
527
528
.. method:: build(options="", devices=None)
529
530
*options* is a string of compiler flags.
531
Returns *self*.
532
533
.. attribute:: kernel_name
534
535
:class:`Kernel` objects can be produced from a built
536
(see :meth:`build`) program simply by attribute lookup.
537
538
.. note::
539
540
The :class:`program_info` attributes live
541
in the same name space and take precedence over
542
:class:`Kernel` names.
543
544
|comparable|
545
546
.. method:: all_kernels()
547
548
Returns a list of all :class:`Kernel` objects in the :class:`Program`.
549
550
.. function:: unload_compiler()
551
552
.. class:: Kernel(program, name)
553
554
.. attribute:: info
555
556
Lower case versions of the :class:`kernel_info` constants
557
may be used as attributes on instances of this class
558
to directly query info attributes.
559
560
.. method:: get_info(param)
561
562
See :class:`kernel_info` for values of *param*.
563
564
.. method:: get_work_group_info(param, device)
565
566
See :class:`kernel_work_group_info` for values of *param*.
567
568
.. method:: set_arg(self, arg)
569
570
*arg* may be
571
572
* `None`: This may be passed for `__global` memory references
573
to pass a NULL pointer to the kernel.
574
* Anything that satisfies the Python buffer interface,
575
in particular :class:`numpy.ndarray`, :class:`str`,
576
or :mod:`numpy`'s sized scalars, such as :class:`numpy.int32`
577
or :class:`numpy.float64`.
578
579
.. note::
580
581
Note that Python's own :class:`int` or :class:`float`
582
objects will not work out of the box. See
583
:meth:`Kernel.set_scalar_arg_dtypes` for a way to make
584
them work. Alternatively, the standard library module
585
:mod:`struct` can be used to convert Python's native
586
number types to binary data in a :class:`str`.
587
588
* An instance of :class:`MemoryObject`. (e.g. :class:`Buffer`,
589
:class:`Image`, etc.)
590
* An instance of :class:`LocalMemory`.
591
* An instance of :class:`Sampler`.
592
593
.. method:: set_args(self, *args)
594
595
Invoke :meth:`set_arg` on each element of *args* in turn.
596
597
.. method:: set_scalar_arg_dtypes(arg_dtypes)
598
599
Inform the wrapper about the sized types of scalar
600
:class:`Kernel` arguments. For each argument,
601
*arg_dtypes* contains an entry. For non-scalars,
602
this must be *None*. For scalars, it must be an
603
object acceptable to the :class:`numpy.dtype`
604
constructor, indicating that the corresponding
605
scalar argument is of that type.
606
607
After invoking this function with the proper information,
608
most suitable number types will automatically be
609
cast to the right type for kernel invocation.
610
611
.. method:: __call__(queue, global_size, local_size, *args, global_offset=None, wait_for=None)
612
613
Use :func:`enqueue_nd_range_kernel` to enqueue a kernel execution, after using
614
:meth:`set_args` to set each argument in turn. See the documentation for
615
:meth:`set_arg` to see what argument types are allowed.
616
|std-enqueue-blurb|
617
618
*None* may be passed for local_size
619
620
.. versionchanged:: 0.92
621
*local_size* was promoted to third positional argument from being a
622
keyword argument. The old keyword argument usage will continue to
623
be accepted with a warning throughout the 0.92 release cycle.
624
This is a backward-compatible change (just barely!) because
625
*local_size* as third positional argument can only be a
626
:class:`tuple` or *None*. :class:`tuple` instances are never valid
627
:class:`Kernel` arguments, and *None* is valid as an argument, but
628
its treatment in the wrapper had a bug (now fixed) that prevented
629
it from working.
630
631
|comparable|
632
633
.. class:: LocalMemory(size)
634
635
A helper class to pass `__local` memory arguments to kernels.
636
637
.. versionadded:: 0.91.2
638
639
.. attribute:: size
640
641
The size of local buffer in bytes to be provided.
642
643
.. function:: enqueue_nd_range_kernel(queue, kernel, global_work_size, local_work_size, global_work_offset=None, wait_for=None)
644
645
|std-enqueue-blurb|
646
647
.. function:: enqueue_task(queue, kernel, wait_for=None)
648
649
|std-enqueue-blurb|
650
651
.. _gl-interop:
652
653
GL Interoperability
654
-------------------
655
656
Functionality in this section is only available when PyOpenCL is compiled
657
with GL support. See :func:`have_gl`.
658
659
.. versionadded:: 0.91
660
661
.. function:: have_gl()
662
663
Return *True* if PyOpenCL was compiled with OpenGL interoperability, otherwise *False*.
664
665
.. class:: GLBuffer(context, flags, bufobj)
666
667
:class:`GLBuffer` is a subclass of :class:`MemoryObject`.
668
669
.. attribute:: gl_object
670
671
.. class:: GLRenderBuffer(context, flags, bufobj)
672
673
:class:`GLRenderBuffer` is a subclass of :class:`MemoryObject`.
674
675
.. attribute:: gl_object
676
677
.. class:: GLTexture(context, flags, texture_target, miplevel, texture, dims)
678
679
*dims* is either 2 or 3.
680
:class:`GLTexture` is a subclass of :class:`Image`.
681
682
.. attribute:: gl_object
683
684
.. method:: get_gl_texture_info(param)
685
686
See :class:`gl_texture_info` for values of *param*. Only available when PyOpenCL is compiled with GL support. See :func:`have_gl`.
687
688
.. function:: enqueue_acquire_gl_objects(queue, mem_objects, wait_for=None)
689
690
*mem_objects* is a list of :class:`MemoryObject` instances.
691
|std-enqueue-blurb|
692
693
.. function:: enqueue_release_gl_objects(queue, mem_objects, wait_for=None)
694
695
*mem_objects* is a list of :class:`MemoryObject` instances. |std-enqueue-blurb|
696
697
.. function:: get_gl_context_info_khr(properties, param_name)
698
699
Get information on which CL device corresponds to a given
700
GL/EGL/WGL/CGL device.
701
702
See the :class:`Context` constructor for the meaning of
703
*properties* and :class:`gl_context_info` for *param_name*.
Loggerhead is a web-based interface for Breezy
Version: 2.0.1