ViewVC Help

View File | Revision Log | Show Annotations | Download File

/cvs/OpenCL/OpenCL.pm

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.52 by root, Tue Apr 24 14:24:42 2012 UTC vs.
Revision 1.74 by root, Fri May 4 15:04:51 2012 UTC

…		…
43		43
44	OpenCL::Event objects are used to signal when something is complete.	44	OpenCL::Event objects are used to signal when something is complete.
45		45
46	=head2 HELPFUL RESOURCES	46	=head2 HELPFUL RESOURCES
47		47
48	The OpenCL spec used to develop this module (1.2 spec was available, but	48	The OpenCL specs used to develop this module - download these and keept
49	no implementation was available to me :).	49	hema round, they are required reference material:
50		50
51	http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf	51	http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf
		52	http://www.khronos.org/registry/cl/specs/opencl-1.2.pdf
		53	http://www.khronos.org/registry/cl/specs/opencl-1.2-extensions.pdf
52		54
53	OpenCL manpages:	55	OpenCL manpages:
54		56
55	http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/	57	http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/
		58	http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/
56		59
57	If you are into UML class diagrams, the following diagram might help - if	60	If you are into UML class diagrams, the following diagram might help - if
58	not, it will be mildly cobfusing:	61	not, it will be mildly confusing (also, the class hierarchy of this module
		62	is much more fine-grained):
59		63
60	http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/classDiagram.html	64	http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/classDiagram.html
61		65
62	Here's a tutorial from AMD (very AMD-centric, too), not sure how useful it	66	Here's a tutorial from AMD (very AMD-centric, too), not sure how useful it
63	is, but at least it's free of charge:	67	is, but at least it's free of charge:
64		68
65	http://developer.amd.com/zones/OpenCLZone/courses/Documents/Introduction_to_OpenCL_Programming%20Training_Guide%20%28201005%29.pdf	69	http://developer.amd.com/zones/OpenCLZone/courses/Documents/Introduction_to_OpenCL_Programming%20Training_Guide%20%28201005%29.pdf
…		…
138	=head2 Create a buffer with some predefined data, read it back synchronously,	142	=head2 Create a buffer with some predefined data, read it back synchronously,
139	then asynchronously.	143	then asynchronously.
140		144
141	my $buf = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, "helmut");	145	my $buf = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, "helmut");
142		146
143	$queue->enqueue_read_buffer ($buf, 1, 1, 3, my $data);	147	$queue->read_buffer ($buf, 1, 1, 3, my $data);
144	print "$data\n";	148	print "$data\n";
145		149
146	my $ev = $queue->enqueue_read_buffer ($buf, 0, 1, 3, my $data);	150	my $ev = $queue->read_buffer ($buf, 0, 1, 3, my $data);
147	$ev->wait;	151	$ev->wait;
148	print "$data\n"; # prints "elm"	152	print "$data\n"; # prints "elm"
149		153
150	=head2 Create and build a program, then create a kernel out of one of its	154	=head2 Create and build a program, then create a kernel out of one of its
151	functions.	155	functions.
…		…
171	# set buffer	175	# set buffer
172	$kernel->set_buffer (0, $input);	176	$kernel->set_buffer (0, $input);
173	$kernel->set_buffer (1, $output);	177	$kernel->set_buffer (1, $output);
174		178
175	# execute it for all 4 numbers	179	# execute it for all 4 numbers
176	$queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef);	180	$queue->nd_range_kernel ($kernel, undef, [4], undef);
177		181
178	# enqueue a synchronous read	182	# enqueue a synchronous read
179	$queue->enqueue_read_buffer ($output, 1, 0, OpenCL::SIZEOF_FLOAT * 4, my $data);	183	$queue->read_buffer ($output, 1, 0, OpenCL::SIZEOF_FLOAT * 4, my $data);
180		184
181	# print the results:	185	# print the results:
182	printf "%s\n", join ", ", unpack "f*", $data;	186	printf "%s\n", join ", ", unpack "f*", $data;
183		187
184	=head2 The same enqueue operations as before, but assuming an out-of-order queue,	188	=head2 The same enqueue operations as before, but assuming an out-of-order queue,
185	showing off barriers.	189	showing off barriers.
186		190
187	# execute it for all 4 numbers	191	# execute it for all 4 numbers
188	$queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef);	192	$queue->nd_range_kernel ($kernel, undef, [4], undef);
189		193
190	# enqueue a barrier to ensure in-order execution	194	# enqueue a barrier to ensure in-order execution
191	$queue->enqueue_barrier;	195	$queue->barrier;
192		196
193	# enqueue an async read	197	# enqueue an async read
194	$queue->enqueue_read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data);	198	$queue->read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data);
195		199
196	# wait for all requests to finish	200	# wait for all requests to finish
197	$queue->finish;	201	$queue->finish;
198		202
199	=head2 The same enqueue operations as before, but assuming an out-of-order queue,	203	=head2 The same enqueue operations as before, but assuming an out-of-order queue,
200	showing off event objects and wait lists.	204	showing off event objects and wait lists.
201		205
202	# execute it for all 4 numbers	206	# execute it for all 4 numbers
203	my $ev = $queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef);	207	my $ev = $queue->nd_range_kernel ($kernel, undef, [4], undef);
204		208
205	# enqueue an async read	209	# enqueue an async read
206	$ev = $queue->enqueue_read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data, $ev);	210	$ev = $queue->read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data, $ev);
207		211
208	# wait for the last event to complete	212	# wait for the last event to complete
209	$ev->wait;	213	$ev->wait;
210		214
211	=head2 Use the OpenGL module to share a texture between OpenCL and OpenGL and draw some julia	215	=head2 Use the OpenGL module to share a texture between OpenCL and OpenGL and draw some julia
212	set tunnel effect.	216	set flight effect.
213		217
214	This is quite a long example to get you going.	218	This is quite a long example to get you going - you can download it from
		219	L<http://cvs.schmorp.de/OpenCL/examples/juliaflight>.
215		220
216	use OpenGL ":all";	221	use OpenGL ":all";
217	use OpenCL;	222	use OpenCL;
218		223
		224	my $S = $ARGV[0] || 256; # window/texture size, smaller is faster
		225
219	# open a window and create a gl texture	226	# open a window and create a gl texture
220	OpenGL::glpOpenWindow width => 256, height => 256;	227	OpenGL::glpOpenWindow width => $S, height => $S;
221	my $texid = glGenTextures_p 1;	228	my $texid = glGenTextures_p 1;
222	glBindTexture GL_TEXTURE_2D, $texid;	229	glBindTexture GL_TEXTURE_2D, $texid;
223	glTexImage2D_c GL_TEXTURE_2D, 0, GL_RGBA8, 256, 256, 0, GL_RGBA, GL_UNSIGNED_BYTE, 0;	230	glTexImage2D_c GL_TEXTURE_2D, 0, GL_RGBA8, $S, $S, 0, GL_RGBA, GL_UNSIGNED_BYTE, 0;
224		231
225	# find and use the first opencl device that let's us get a shared opengl context	232	# find and use the first opencl device that let's us get a shared opengl context
226	my $platform;	233	my $platform;
227	my $dev;	234	my $dev;
228	my $ctx;	235	my $ctx;
…		…
247	# now the boring opencl code	254	# now the boring opencl code
248	my $src = <<EOF;	255	my $src = <<EOF;
249	kernel void	256	kernel void
250	juliatunnel (write_only image2d_t img, float time)	257	juliatunnel (write_only image2d_t img, float time)
251	{	258	{
252	float2 p = (float2)(get_global_id (0), get_global_id (1)) / 256.f * 2.f - 1.f;	259	int2 xy = (int2)(get_global_id (0), get_global_id (1));
		260	float2 p = convert_float2 (xy) / $S.f * 2.f - 1.f;
253		261
254	float2 m = (float2)(1.f, p.y) / fabs (p.x);	262	float2 m = (float2)(1.f, p.y) / fabs (p.x); // tunnel
255	m.x = fabs (fmod (m.x + time * 0.05f, 4.f)) - 2.f;	263	m.x = fabs (fmod (m.x + time * 0.05f, 4.f) - 2.f);
256		264
257	float2 z = m;	265	float2 z = m;
258	float2 c = (float2)(sin (time * 0.05005), cos (time * 0.06001));	266	float2 c = (float2)(sin (time * 0.01133f), cos (time * 0.02521f));
259		267
260	for (int i = 0; i < 25 && dot (z, z) < 4.f; ++i)	268	for (int i = 0; i < 25 && dot (z, z) < 4.f; ++i) // standard julia
261	z = (float2)(z.x * z.x - z.y * z.y, 2.f * z.x * z.y) + c;	269	z = (float2)(z.x * z.x - z.y * z.y, 2.f * z.x * z.y) + c;
262		270
263	float3 colour = (float3)(z.x, z.y, z.x * z.y);	271	float3 colour = (float3)(z.x, z.y, atan2 (z.y, z.x));
264	write_imagef (img, (int2)(get_global_id (0), get_global_id (1)), (float4)(colour * p.x * p.x, 1.));	272	write_imagef (img, xy, (float4)(colour * p.x * p.x, 1.));
265	}	273	}
266	EOF	274	EOF
267		275
268	my $prog = $ctx->build_program ($src);	276	my $prog = $ctx->build_program ($src);
269	my $kernel = $prog->kernel ("juliatunnel");	277	my $kernel = $prog->kernel ("juliatunnel");
270		278
271	# program compiled, kernel ready, now draw and loop	279	# program compiled, kernel ready, now draw and loop
272		280
273	for (my $time; ; ++$time) {	281	for (my $time; ; ++$time) {
274	# acquire objects from opengl	282	# acquire objects from opengl
275	$queue->enqueue_acquire_gl_objects ([$tex]);	283	$queue->acquire_gl_objects ([$tex]);
276		284
277	# configure and run our kernel	285	# configure and run our kernel
278	$kernel->set_image2d (0, $tex);	286	$kernel->setf ("mf", $tex, $time*2); # mf = memory object, float
279	$kernel->set_float (1, $time);
280	$queue->enqueue_nd_range_kernel ($kernel, undef, [256, 256], undef);	287	$queue->nd_range_kernel ($kernel, undef, [$S, $S], undef);
281		288
282	# release objects to opengl again	289	# release objects to opengl again
283	$queue->enqueue_release_gl_objects ([$tex]);	290	$queue->release_gl_objects ([$tex]);
284		291
285	# wait	292	# wait
286	$queue->finish;	293	$queue->finish;
287		294
288	# now draw the texture, the defaults should be all right	295	# now draw the texture, the defaults should be all right
…		…
298		305
299	glXSwapBuffers;	306	glXSwapBuffers;
300		307
301	select undef, undef, undef, 1/60;	308	select undef, undef, undef, 1/60;
302	}	309	}
		310
		311	=head2 How to modify the previous example to not rely on GL sharing.
		312
		313	For those poor souls with only a sucky CPU OpenCL implementation, you
		314	currently have to read the image into some perl scalar, and then modify a
		315	texture or use glDrawPixels or so).
		316
		317	First, when you don't need gl sharing, you can create the context much simpler:
		318
		319	$ctx = $platform->context (undef, [$dev])
		320
		321	To use a texture, you would modify the above example by creating an
		322	OpenCL::Image manually instead of deriving it from a texture:
		323
		324	my $tex = $ctx->image2d (OpenCL::MEM_WRITE_ONLY, OpenCL::RGBA, OpenCL::UNORM_INT8, $S, $S);
		325
		326	And in the draw loop, intead of acquire_gl_objects/release_gl_objects, you
		327	would read the image2d after the kernel has written it:
		328
		329	$queue->read_image ($tex, 0, 0, 0, 0, $S, $S, 1, 0, 0, my $data);
		330
		331	And then you would upload the pixel data to the texture (or use glDrawPixels):
		332
		333	glTexSubImage2D_s GL_TEXTURE_2D, 0, 0, 0, $S, $S, GL_RGBA, GL_UNSIGNED_BYTE, $data;
		334
		335	The fully modified example can be found at
		336	L<http://cvs.schmorp.de/OpenCL/examples/juliaflight-nosharing>.
		337
		338	=head2 Julia sets look soooo 80ies.
		339
		340	Then colour them differently, e.g. using orbit traps! Replace the loop and
		341	colour calculation from the previous examples by this:
		342
		343	float2 dm = (float2)(1.f, 1.f);
		344
		345	for (int i = 0; i < 25; ++i)
		346	{
		347	z = (float2)(z.x * z.x - z.y * z.y, 2.f * z.x * z.y) + c;
		348	dm = fmin (dm, (float2)(fabs (dot (z, z) - 1.f), fabs (z.x - 1.f)));
		349	}
		350
		351	float3 colour = (float3)(dm.x * dm.y, dm.x * dm.y, dm.x);
		352
		353	Also try C<-10.f> instead of C<-1.f>.
303		354
304	=head1 DOCUMENTATION	355	=head1 DOCUMENTATION
305		356
306	=head2 BASIC CONVENTIONS	357	=head2 BASIC CONVENTIONS
307		358
…		…
376		427
377	For this to work, the OpenGL library must be loaded, a GLX context must	428	For this to work, the OpenGL library must be loaded, a GLX context must
378	have been created and be made current, and C<dlsym> must be available and	429	have been created and be made current, and C<dlsym> must be available and
379	capable of finding the function via C<RTLD_DEFAULT>.	430	capable of finding the function via C<RTLD_DEFAULT>.
380		431
		432	=head2 EVENT SYSTEM
		433
		434	OpenCL can generate a number of (potentially) asynchronous events, for
		435	example, after compiling a program, to signal a context-related error or,
		436	perhaps most important, to signal completion of queued jobs (by setting
		437	callbacks on OpenCL::Event objects).
		438
		439	The OpenCL module converts all these callbacks into events - you can
		440	still register callbacks, but they are not executed when your OpenCL
		441	implementation calls the actual callback, but only later. Therefore, none
		442	of the limitations of OpenCL callbacks apply to the perl implementation:
		443	it is perfectly safe to make blocking operations from event callbacks, and
		444	enqueued operations don't need to be flushed.
		445
		446	To facilitate this, this module maintains an event queue - each
		447	time an asynchronous event happens, it is queued, and perl will be
		448	interrupted. This is implemented via the L<Async::Interrupt> module. In
		449	addition, this module has L<AnyEvent> support, so it can seamlessly
		450	integrate itself into many event loops.
		451
		452	Since L<Async::Interrupt> is a bit hard to understand, here are some case examples:
		453
		454	=head3 Don't use callbacks.
		455
		456	When your program never uses any callbacks, then there will never be any
		457	notifications you need to take care of, and therefore no need to worry
		458	about all this.
		459
		460	You can achieve a great deal by explicitly waiting for events, or using
		461	barriers and flush calls. In many programs, there is no need at all to
		462	tinker with asynchronous events.
		463
		464	=head3 Use AnyEvent
		465
		466	This module automatically registers a watcher that invokes all outstanding
		467	event callbacks when AnyEvent is initialised (and block asynchronous
		468	interruptions). Using this mode of operations is the safest and most
		469	recommended one.
		470
		471	To use this, simply use AnyEvent and this module normally, make sure you
		472	have an event loop running:
		473
		474	use Gtk2 -init;
		475	use AnyEvent;
		476
		477	# initialise AnyEvent, by creating a watcher, or:
		478	AnyEvent::detect;
		479
		480	my $e = $queue->marker;
		481	$e->cb (sub {
		482	warn "opencl is finished\n";
		483	})
		484
		485	main Gtk2;
		486
		487	Note that this module will not initialise AnyEvent for you. Before
		488	AnyEvent is initialised, the module will asynchronously interrupt perl
		489	instead. To avoid any surprises, it's best to explicitly initialise
		490	AnyEvent.
		491
		492	You can temporarily enable asynchronous interruptions (see next paragraph)
		493	by calling C<$OpenCL::INTERRUPT->unblock> and disable them again by
		494	calling C<$OpenCL::INTERRUPT->block>.
		495
		496	=head3 Let yourself be interrupted at any time
		497
		498	This mode is the default unless AnyEvent is loaded and initialised. In
		499	this mode, OpenCL asynchronously interrupts a running perl program. The
		500	emphasis is on both I<asynchronously> and I<running> here.
		501
		502	Asynchronously means that perl might execute your callbacks at any
		503	time. For example, in the following code (I<THAT YOU SHOULD NOT COPY>),
		504	the C<until> loop following the marker call will be interrupted by the
		505	callback:
		506
		507	my $e = $queue->marker;
		508	my $flag;
		509	$e->cb (sub { $flag = 1 });
		510	1 until $flag;
		511	# $flag is now 1
		512
		513	The reason why you shouldn't blindly copy the above code is that
		514	busy waiting is a really really bad thing, and really really bad for
		515	performance.
		516
		517	While at first this asynchronous business might look exciting, it can be
		518	really hard, because you need to be prepared for the callback code to be
		519	executed at any time, which limits the amount of things the callback code
		520	can do safely.
		521
		522	This can be mitigated somewhat by using C<<
		523	$OpenCL::INTERRUPT->scope_block >> (see the L<Async::Interrupt>
		524	documentation for details).
		525
		526	The other problem is that your program must be actively I<running> to be
		527	interrupted. When you calculate stuff, your program is running. When you
		528	hang in some C functions or other block execution (by calling C<sleep>,
		529	C<select>, running an event loop and so on), your program is waiting, not
		530	running.
		531
		532	One way around that would be to attach a read watcher to your event loop,
		533	listening for events on C<< $OpenCL::INTERRUPT->pipe_fileno >>, using a
		534	dummy callback (C<sub { }>) to temporarily execute some perl code.
		535
		536	That is then awfully close to using the built-in AnyEvent support above,
		537	though, so consider that one instead.
		538
		539	=head3 Be creative
		540
		541	OpenCL exports the L<Async::Interrupt> object it uses in the global
		542	variable C<$OpenCL::INTERRUPT>. You can configure it in any way you like.
		543
		544	So if you want to feel like a real pro, err, wait, if you feel no risk
		545	menas no fun, you can experiment by implementing your own mode of
		546	operations.
		547
381	=cut	548	=cut
382		549
383	package OpenCL;	550	package OpenCL;
384		551
385	use common::sense;	552	use common::sense;
		553	use Carp ();
		554	use Async::Interrupt ();
		555
		556	our $POLL_FUNC; # set by XS
386		557
387	BEGIN {	558	BEGIN {
388	our $VERSION = '0.96';	559	our $VERSION = '0.99';
389		560
390	require XSLoader;	561	require XSLoader;
391	XSLoader::load (__PACKAGE__, $VERSION);	562	XSLoader::load (__PACKAGE__, $VERSION);
392		563
393	@OpenCL::Platform::ISA =	564	@OpenCL::Platform::ISA =
…		…
398	@OpenCL::Sampler::ISA =	569	@OpenCL::Sampler::ISA =
399	@OpenCL::Program::ISA =	570	@OpenCL::Program::ISA =
400	@OpenCL::Kernel::ISA =	571	@OpenCL::Kernel::ISA =
401	@OpenCL::Event::ISA = OpenCL::Object::;	572	@OpenCL::Event::ISA = OpenCL::Object::;
402		573
		574	@OpenCL::SubDevice::ISA = OpenCL::Device::;
		575
403	@OpenCL::Buffer::ISA =	576	@OpenCL::Buffer::ISA =
404	@OpenCL::Image::ISA = OpenCL::Memory::;	577	@OpenCL::Image::ISA = OpenCL::Memory::;
405		578
406	@OpenCL::BufferObj::ISA = OpenCL::Buffer::;	579	@OpenCL::BufferObj::ISA = OpenCL::Buffer::;
407		580
…		…
411	@OpenCL::Image1D::ISA =	584	@OpenCL::Image1D::ISA =
412	@OpenCL::Image1DArray::ISA =	585	@OpenCL::Image1DArray::ISA =
413	@OpenCL::Image1DBuffer::ISA = OpenCL::Image::;	586	@OpenCL::Image1DBuffer::ISA = OpenCL::Image::;
414		587
415	@OpenCL::UserEvent::ISA = OpenCL::Event::;	588	@OpenCL::UserEvent::ISA = OpenCL::Event::;
		589
		590	@OpenCL::MappedBuffer::ISA =
		591	@OpenCL::MappedImage::ISA = OpenCL::Mapped::;
416	}	592	}
417		593
418	=head2 THE OpenCL PACKAGE	594	=head2 THE OpenCL PACKAGE
419		595
420	=over 4	596	=over 4
…		…
422	=item $int = OpenCL::errno	598	=item $int = OpenCL::errno
423		599
424	The last error returned by a function - it's only valid after an error occured	600	The last error returned by a function - it's only valid after an error occured
425	and before calling another OpenCL function.	601	and before calling another OpenCL function.
426		602
427	=item $str = OpenCL::err2str $errval	603	=item $str = OpenCL::err2str [$errval]
428		604
429	Comverts an error value into a human readable string.	605	Converts an error value into a human readable string. IF no error value is
		606	given, then the last error will be used (as returned by OpenCL::errno).
430		607
431	=item $str = OpenCL::enum2str $enum	608	=item $str = OpenCL::enum2str $enum
432		609
433	Converts most enum values (of parameter names, image format constants,	610	Converts most enum values (of parameter names, image format constants,
434	object types, addressing and filter modes, command types etc.) into a	611	object types, addressing and filter modes, command types etc.) into a
…		…
440		617
441	Returns all available OpenCL::Platform objects.	618	Returns all available OpenCL::Platform objects.
442		619
443	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformIDs.html>	620	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformIDs.html>
444		621
445	=item $ctx = OpenCL::context_from_type $properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $notify = undef	622	=item $ctx = OpenCL::context_from_type $properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $callback->($err, $pvt) = $print_stderr
446		623
447	Tries to create a context from a default device and platform - never worked for me.	624	Tries to create a context from a default device and platform type - never worked for me.
		625
		626	type: OpenCL::DEVICE_TYPE_DEFAULT, OpenCL::DEVICE_TYPE_CPU, OpenCL::DEVICE_TYPE_GPU,
		627	OpenCL::DEVICE_TYPE_ACCELERATOR, OpenCL::DEVICE_TYPE_CUSTOM, OpenCL::DEVICE_TYPE_ALL.
448		628
449	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>	629	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>
450		630
		631	=item $ctx = OpenCL::context $properties, \@devices, $callback->($err, $pvt) = $print_stderr)
		632
		633	Create a new OpenCL::Context object using the given device object(s). This
		634	function isn't implemented yet, use C<< $platform->context >> instead.
		635
		636	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html>
		637
451	=item OpenCL::wait_for_events $wait_events...	638	=item OpenCL::wait_for_events $wait_events...
452		639
453	Waits for all events to complete.	640	Waits for all events to complete.
454		641
455	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html>	642	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html>
		643
		644	=item OpenCL::poll
		645
		646	Checks if there are any outstanding events (see L<EVENT SYSTEM>) and
		647	invokes their callbacks.
		648
		649	=item $OpenCL::INTERRUPT
		650
		651	The L<Async::Interrupt> object used to signal asynchronous events (see
		652	L<EVENT SYSTEM>).
		653
		654	=cut
		655
		656	our $INTERRUPT = new Async::Interrupt c_cb => [$POLL_FUNC, 0];
		657
		658	&_eq_initialise ($INTERRUPT->signal_func);
		659
		660	=item $OpenCL::WATCHER
		661
		662	The L<AnyEvent> watcher object used to watch for asynchronous events (see
		663	L<EVENT SYSTEM>). This variable is C<undef> until L<AnyEvent> has been
		664	loaded I<and> initialised (e.g. by calling C<AnyEvent::detect>).
		665
		666	=cut
		667
		668	our $WATCHER;
		669
		670	sub _init_anyevent {
		671	$INTERRUPT->block;
		672	$WATCHER = AE::io ($INTERRUPT->pipe_fileno, 0, sub { $INTERRUPT->handle });
		673	}
		674
		675	if (defined $AnyEvent::MODEL) {
		676	_init_anyevent;
		677	} else {
		678	push @AnyEvent::post_detect, \&_init_anyevent;
		679	}
456		680
457	=back	681	=back
458		682
459	=head2 THE OpenCL::Object CLASS	683	=head2 THE OpenCL::Object CLASS
460		684
…		…
472	C<IV> type in your code and cast that to the correct type.	696	C<IV> type in your code and cast that to the correct type.
473		697
474	=cut	698	=cut
475		699
476	sub OpenCL::Object::id {	700	sub OpenCL::Object::id {
		701	ref $_[0] eq "SCALAR"
477	${$_[0]}	702	? ${ $_[0] }
		703	: $_[0][0]
478	}	704	}
479		705
480	=back	706	=back
481		707
482	=head2 THE OpenCL::Platform CLASS	708	=head2 THE OpenCL::Platform CLASS
…		…
485		711
486	=item @devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL)	712	=item @devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL)
487		713
488	Returns a list of matching OpenCL::Device objects.	714	Returns a list of matching OpenCL::Device objects.
489		715
490	=item $ctx = $platform->context_from_type ($properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $notify = undef)	716	=item $ctx = $platform->context_from_type ($properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $callback->($err, $pvt) = $print_stderr)
491		717
492	Tries to create a context. Never worked for me, and you need devices explicitly anyway.	718	Tries to create a context. Never worked for me, and you need devices explicitly anyway.
493		719
494	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>	720	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>
495		721
496	=item $ctx = $platform->context ($properties = undef, @$devices, $notify = undef)	722	=item $ctx = $platform->context ($properties, \@devices, $callback->($err, $pvt) = $print_stderr)
497		723
498	Create a new OpenCL::Context object using the given device object(s)- a	724	Create a new OpenCL::Context object using the given device object(s)- a
499	CL_CONTEXT_PLATFORM property is supplied automatically.	725	CL_CONTEXT_PLATFORM property is supplied automatically.
500		726
501	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html>	727	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html>
…		…
520		746
521	=for gengetinfo begin platform	747	=for gengetinfo begin platform
522		748
523	=item $string = $platform->profile	749	=item $string = $platform->profile
524		750
525	Calls C<clGetPlatformInfo> with C<CL_PLATFORM_PROFILE> and returns the result.	751	Calls C<clGetPlatformInfo> with C<OpenCL::PLATFORM_PROFILE> and returns the result.
526		752
527	=item $string = $platform->version	753	=item $string = $platform->version
528		754
529	Calls C<clGetPlatformInfo> with C<CL_PLATFORM_VERSION> and returns the result.	755	Calls C<clGetPlatformInfo> with C<OpenCL::PLATFORM_VERSION> and returns the result.
530		756
531	=item $string = $platform->name	757	=item $string = $platform->name
532		758
533	Calls C<clGetPlatformInfo> with C<CL_PLATFORM_NAME> and returns the result.	759	Calls C<clGetPlatformInfo> with C<OpenCL::PLATFORM_NAME> and returns the result.
534		760
535	=item $string = $platform->vendor	761	=item $string = $platform->vendor
536		762
537	Calls C<clGetPlatformInfo> with C<CL_PLATFORM_VENDOR> and returns the result.	763	Calls C<clGetPlatformInfo> with C<OpenCL::PLATFORM_VENDOR> and returns the result.
538		764
539	=item $string = $platform->extensions	765	=item $string = $platform->extensions
540		766
541	Calls C<clGetPlatformInfo> with C<CL_PLATFORM_EXTENSIONS> and returns the result.	767	Calls C<clGetPlatformInfo> with C<OpenCL::PLATFORM_EXTENSIONS> and returns the result.
542		768
543	=for gengetinfo end platform	769	=for gengetinfo end platform
544		770
545	=back	771	=back
546		772
…		…
552		778
553	See C<< $platform->info >> for details.	779	See C<< $platform->info >> for details.
554		780
555	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html>	781	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html>
556		782
		783	=item @devices = $device->sub_devices (\@properties)
		784
		785	Creates OpencL::SubDevice objects by partitioning an existing device.
		786
		787	L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCreateSubDevices.html>
		788
557	=for gengetinfo begin device	789	=for gengetinfo begin device
558		790
559	=item $device_type = $device->type	791	=item $device_type = $device->type
560		792
561	Calls C<clGetDeviceInfo> with C<CL_DEVICE_TYPE> and returns the result.	793	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_TYPE> and returns the result.
562		794
563	=item $uint = $device->vendor_id	795	=item $uint = $device->vendor_id
564		796
565	Calls C<clGetDeviceInfo> with C<CL_DEVICE_VENDOR_ID> and returns the result.	797	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_VENDOR_ID> and returns the result.
566		798
567	=item $uint = $device->max_compute_units	799	=item $uint = $device->max_compute_units
568		800
569	Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_COMPUTE_UNITS> and returns the result.	801	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_COMPUTE_UNITS> and returns the result.
570		802
571	=item $uint = $device->max_work_item_dimensions	803	=item $uint = $device->max_work_item_dimensions
572		804
573	Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS> and returns the result.	805	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_WORK_ITEM_DIMENSIONS> and returns the result.
574		806
575	=item $int = $device->max_work_group_size	807	=item $int = $device->max_work_group_size
576		808
577	Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_WORK_GROUP_SIZE> and returns the result.	809	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_WORK_GROUP_SIZE> and returns the result.
578		810
579	=item @ints = $device->max_work_item_sizes	811	=item @ints = $device->max_work_item_sizes
580		812
581	Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_WORK_ITEM_SIZES> and returns the result.	813	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_WORK_ITEM_SIZES> and returns the result.
582		814
583	=item $uint = $device->preferred_vector_width_char	815	=item $uint = $device->preferred_vector_width_char
584		816
585	Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR> and returns the result.	817	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PREFERRED_VECTOR_WIDTH_CHAR> and returns the result.
586		818
587	=item $uint = $device->preferred_vector_width_short	819	=item $uint = $device->preferred_vector_width_short
588		820
589	Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT> and returns the result.	821	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PREFERRED_VECTOR_WIDTH_SHORT> and returns the result.
590		822
591	=item $uint = $device->preferred_vector_width_int	823	=item $uint = $device->preferred_vector_width_int
592		824
593	Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT> and returns the result.	825	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PREFERRED_VECTOR_WIDTH_INT> and returns the result.
594		826
595	=item $uint = $device->preferred_vector_width_long	827	=item $uint = $device->preferred_vector_width_long
596		828
597	Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG> and returns the result.	829	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PREFERRED_VECTOR_WIDTH_LONG> and returns the result.
598		830
599	=item $uint = $device->preferred_vector_width_float	831	=item $uint = $device->preferred_vector_width_float
600		832
601	Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT> and returns the result.	833	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT> and returns the result.
602		834
603	=item $uint = $device->preferred_vector_width_double	835	=item $uint = $device->preferred_vector_width_double
604		836
605	Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE> and returns the result.	837	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE> and returns the result.
606		838
607	=item $uint = $device->max_clock_frequency	839	=item $uint = $device->max_clock_frequency
608		840
609	Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_CLOCK_FREQUENCY> and returns the result.	841	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_CLOCK_FREQUENCY> and returns the result.
610		842
611	=item $bitfield = $device->address_bits	843	=item $bitfield = $device->address_bits
612		844
613	Calls C<clGetDeviceInfo> with C<CL_DEVICE_ADDRESS_BITS> and returns the result.	845	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_ADDRESS_BITS> and returns the result.
614		846
615	=item $uint = $device->max_read_image_args	847	=item $uint = $device->max_read_image_args
616		848
617	Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_READ_IMAGE_ARGS> and returns the result.	849	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_READ_IMAGE_ARGS> and returns the result.
618		850
619	=item $uint = $device->max_write_image_args	851	=item $uint = $device->max_write_image_args
620		852
621	Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_WRITE_IMAGE_ARGS> and returns the result.	853	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_WRITE_IMAGE_ARGS> and returns the result.
622		854
623	=item $ulong = $device->max_mem_alloc_size	855	=item $ulong = $device->max_mem_alloc_size
624		856
625	Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_MEM_ALLOC_SIZE> and returns the result.	857	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_MEM_ALLOC_SIZE> and returns the result.
626		858
627	=item $int = $device->image2d_max_width	859	=item $int = $device->image2d_max_width
628		860
629	Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE2D_MAX_WIDTH> and returns the result.	861	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_IMAGE2D_MAX_WIDTH> and returns the result.
630		862
631	=item $int = $device->image2d_max_height	863	=item $int = $device->image2d_max_height
632		864
633	Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE2D_MAX_HEIGHT> and returns the result.	865	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_IMAGE2D_MAX_HEIGHT> and returns the result.
634		866
635	=item $int = $device->image3d_max_width	867	=item $int = $device->image3d_max_width
636		868
637	Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE3D_MAX_WIDTH> and returns the result.	869	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_IMAGE3D_MAX_WIDTH> and returns the result.
638		870
639	=item $int = $device->image3d_max_height	871	=item $int = $device->image3d_max_height
640		872
641	Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE3D_MAX_HEIGHT> and returns the result.	873	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_IMAGE3D_MAX_HEIGHT> and returns the result.
642		874
643	=item $int = $device->image3d_max_depth	875	=item $int = $device->image3d_max_depth
644		876
645	Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE3D_MAX_DEPTH> and returns the result.	877	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_IMAGE3D_MAX_DEPTH> and returns the result.
646		878
647	=item $uint = $device->image_support	879	=item $uint = $device->image_support
648		880
649	Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE_SUPPORT> and returns the result.	881	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_IMAGE_SUPPORT> and returns the result.
650		882
651	=item $int = $device->max_parameter_size	883	=item $int = $device->max_parameter_size
652		884
653	Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_PARAMETER_SIZE> and returns the result.	885	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_PARAMETER_SIZE> and returns the result.
654		886
655	=item $uint = $device->max_samplers	887	=item $uint = $device->max_samplers
656		888
657	Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_SAMPLERS> and returns the result.	889	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_SAMPLERS> and returns the result.
658		890
659	=item $uint = $device->mem_base_addr_align	891	=item $uint = $device->mem_base_addr_align
660		892
661	Calls C<clGetDeviceInfo> with C<CL_DEVICE_MEM_BASE_ADDR_ALIGN> and returns the result.	893	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MEM_BASE_ADDR_ALIGN> and returns the result.
662		894
663	=item $uint = $device->min_data_type_align_size	895	=item $uint = $device->min_data_type_align_size
664		896
665	Calls C<clGetDeviceInfo> with C<CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE> and returns the result.	897	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MIN_DATA_TYPE_ALIGN_SIZE> and returns the result.
666		898
667	=item $device_fp_config = $device->single_fp_config	899	=item $device_fp_config = $device->single_fp_config
668		900
669	Calls C<clGetDeviceInfo> with C<CL_DEVICE_SINGLE_FP_CONFIG> and returns the result.	901	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_SINGLE_FP_CONFIG> and returns the result.
670		902
671	=item $device_mem_cache_type = $device->global_mem_cache_type	903	=item $device_mem_cache_type = $device->global_mem_cache_type
672		904
673	Calls C<clGetDeviceInfo> with C<CL_DEVICE_GLOBAL_MEM_CACHE_TYPE> and returns the result.	905	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_GLOBAL_MEM_CACHE_TYPE> and returns the result.
674		906
675	=item $uint = $device->global_mem_cacheline_size	907	=item $uint = $device->global_mem_cacheline_size
676		908
677	Calls C<clGetDeviceInfo> with C<CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE> and returns the result.	909	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_GLOBAL_MEM_CACHELINE_SIZE> and returns the result.
678		910
679	=item $ulong = $device->global_mem_cache_size	911	=item $ulong = $device->global_mem_cache_size
680		912
681	Calls C<clGetDeviceInfo> with C<CL_DEVICE_GLOBAL_MEM_CACHE_SIZE> and returns the result.	913	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_GLOBAL_MEM_CACHE_SIZE> and returns the result.
682		914
683	=item $ulong = $device->global_mem_size	915	=item $ulong = $device->global_mem_size
684		916
685	Calls C<clGetDeviceInfo> with C<CL_DEVICE_GLOBAL_MEM_SIZE> and returns the result.	917	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_GLOBAL_MEM_SIZE> and returns the result.
686		918
687	=item $ulong = $device->max_constant_buffer_size	919	=item $ulong = $device->max_constant_buffer_size
688		920
689	Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE> and returns the result.	921	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_CONSTANT_BUFFER_SIZE> and returns the result.
690		922
691	=item $uint = $device->max_constant_args	923	=item $uint = $device->max_constant_args
692		924
693	Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_CONSTANT_ARGS> and returns the result.	925	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_CONSTANT_ARGS> and returns the result.
694		926
695	=item $device_local_mem_type = $device->local_mem_type	927	=item $device_local_mem_type = $device->local_mem_type
696		928
697	Calls C<clGetDeviceInfo> with C<CL_DEVICE_LOCAL_MEM_TYPE> and returns the result.	929	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_LOCAL_MEM_TYPE> and returns the result.
698		930
699	=item $ulong = $device->local_mem_size	931	=item $ulong = $device->local_mem_size
700		932
701	Calls C<clGetDeviceInfo> with C<CL_DEVICE_LOCAL_MEM_SIZE> and returns the result.	933	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_LOCAL_MEM_SIZE> and returns the result.
702		934
703	=item $boolean = $device->error_correction_support	935	=item $boolean = $device->error_correction_support
704		936
705	Calls C<clGetDeviceInfo> with C<CL_DEVICE_ERROR_CORRECTION_SUPPORT> and returns the result.	937	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_ERROR_CORRECTION_SUPPORT> and returns the result.
706		938
707	=item $int = $device->profiling_timer_resolution	939	=item $int = $device->profiling_timer_resolution
708		940
709	Calls C<clGetDeviceInfo> with C<CL_DEVICE_PROFILING_TIMER_RESOLUTION> and returns the result.	941	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PROFILING_TIMER_RESOLUTION> and returns the result.
710		942
711	=item $boolean = $device->endian_little	943	=item $boolean = $device->endian_little
712		944
713	Calls C<clGetDeviceInfo> with C<CL_DEVICE_ENDIAN_LITTLE> and returns the result.	945	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_ENDIAN_LITTLE> and returns the result.
714		946
715	=item $boolean = $device->available	947	=item $boolean = $device->available
716		948
717	Calls C<clGetDeviceInfo> with C<CL_DEVICE_AVAILABLE> and returns the result.	949	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_AVAILABLE> and returns the result.
718		950
719	=item $boolean = $device->compiler_available	951	=item $boolean = $device->compiler_available
720		952
721	Calls C<clGetDeviceInfo> with C<CL_DEVICE_COMPILER_AVAILABLE> and returns the result.	953	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_COMPILER_AVAILABLE> and returns the result.
722		954
723	=item $device_exec_capabilities = $device->execution_capabilities	955	=item $device_exec_capabilities = $device->execution_capabilities
724		956
725	Calls C<clGetDeviceInfo> with C<CL_DEVICE_EXECUTION_CAPABILITIES> and returns the result.	957	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_EXECUTION_CAPABILITIES> and returns the result.
726		958
727	=item $command_queue_properties = $device->properties	959	=item $command_queue_properties = $device->properties
728		960
729	Calls C<clGetDeviceInfo> with C<CL_DEVICE_QUEUE_PROPERTIES> and returns the result.	961	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_QUEUE_PROPERTIES> and returns the result.
730		962
731	=item $ = $device->platform	963	=item $ = $device->platform
732		964
733	Calls C<clGetDeviceInfo> with C<CL_DEVICE_PLATFORM> and returns the result.	965	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PLATFORM> and returns the result.
734		966
735	=item $string = $device->name	967	=item $string = $device->name
736		968
737	Calls C<clGetDeviceInfo> with C<CL_DEVICE_NAME> and returns the result.	969	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_NAME> and returns the result.
738		970
739	=item $string = $device->vendor	971	=item $string = $device->vendor
740		972
741	Calls C<clGetDeviceInfo> with C<CL_DEVICE_VENDOR> and returns the result.	973	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_VENDOR> and returns the result.
742		974
743	=item $string = $device->driver_version	975	=item $string = $device->driver_version
744		976
745	Calls C<clGetDeviceInfo> with C<CL_DRIVER_VERSION> and returns the result.	977	Calls C<clGetDeviceInfo> with C<OpenCL::DRIVER_VERSION> and returns the result.
746		978
747	=item $string = $device->profile	979	=item $string = $device->profile
748		980
749	Calls C<clGetDeviceInfo> with C<CL_DEVICE_PROFILE> and returns the result.	981	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PROFILE> and returns the result.
750		982
751	=item $string = $device->version	983	=item $string = $device->version
752		984
753	Calls C<clGetDeviceInfo> with C<CL_DEVICE_VERSION> and returns the result.	985	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_VERSION> and returns the result.
754		986
755	=item $string = $device->extensions	987	=item $string = $device->extensions
756		988
757	Calls C<clGetDeviceInfo> with C<CL_DEVICE_EXTENSIONS> and returns the result.	989	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_EXTENSIONS> and returns the result.
758		990
759	=item $uint = $device->preferred_vector_width_half	991	=item $uint = $device->preferred_vector_width_half
760		992
761	Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF> and returns the result.	993	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PREFERRED_VECTOR_WIDTH_HALF> and returns the result.
762		994
763	=item $uint = $device->native_vector_width_char	995	=item $uint = $device->native_vector_width_char
764		996
765	Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_CHAR> and returns the result.	997	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_NATIVE_VECTOR_WIDTH_CHAR> and returns the result.
766		998
767	=item $uint = $device->native_vector_width_short	999	=item $uint = $device->native_vector_width_short
768		1000
769	Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_SHORT> and returns the result.	1001	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_NATIVE_VECTOR_WIDTH_SHORT> and returns the result.
770		1002
771	=item $uint = $device->native_vector_width_int	1003	=item $uint = $device->native_vector_width_int
772		1004
773	Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_INT> and returns the result.	1005	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_NATIVE_VECTOR_WIDTH_INT> and returns the result.
774		1006
775	=item $uint = $device->native_vector_width_long	1007	=item $uint = $device->native_vector_width_long
776		1008
777	Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_LONG> and returns the result.	1009	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_NATIVE_VECTOR_WIDTH_LONG> and returns the result.
778		1010
779	=item $uint = $device->native_vector_width_float	1011	=item $uint = $device->native_vector_width_float
780		1012
781	Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_FLOAT> and returns the result.	1013	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_NATIVE_VECTOR_WIDTH_FLOAT> and returns the result.
782		1014
783	=item $uint = $device->native_vector_width_double	1015	=item $uint = $device->native_vector_width_double
784		1016
785	Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE> and returns the result.	1017	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE> and returns the result.
786		1018
787	=item $uint = $device->native_vector_width_half	1019	=item $uint = $device->native_vector_width_half
788		1020
789	Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF> and returns the result.	1021	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_NATIVE_VECTOR_WIDTH_HALF> and returns the result.
790		1022
791	=item $device_fp_config = $device->double_fp_config	1023	=item $device_fp_config = $device->double_fp_config
792		1024
793	Calls C<clGetDeviceInfo> with C<CL_DEVICE_DOUBLE_FP_CONFIG> and returns the result.	1025	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_DOUBLE_FP_CONFIG> and returns the result.
794		1026
795	=item $device_fp_config = $device->half_fp_config	1027	=item $device_fp_config = $device->half_fp_config
796		1028
797	Calls C<clGetDeviceInfo> with C<CL_DEVICE_HALF_FP_CONFIG> and returns the result.	1029	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_HALF_FP_CONFIG> and returns the result.
798		1030
799	=item $boolean = $device->host_unified_memory	1031	=item $boolean = $device->host_unified_memory
800		1032
801	Calls C<clGetDeviceInfo> with C<CL_DEVICE_HOST_UNIFIED_MEMORY> and returns the result.	1033	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_HOST_UNIFIED_MEMORY> and returns the result.
802		1034
803	=item $device = $device->parent_device_ext	1035	=item $device = $device->parent_device_ext
804		1036
805	Calls C<clGetDeviceInfo> with C<CL_DEVICE_PARENT_DEVICE_EXT> and returns the result.	1037	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PARENT_DEVICE_EXT> and returns the result.
806		1038
807	=item @device_partition_property_exts = $device->partition_types_ext	1039	=item @device_partition_property_exts = $device->partition_types_ext
808		1040
809	Calls C<clGetDeviceInfo> with C<CL_DEVICE_PARTITION_TYPES_EXT> and returns the result.	1041	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PARTITION_TYPES_EXT> and returns the result.
810		1042
811	=item @device_partition_property_exts = $device->affinity_domains_ext	1043	=item @device_partition_property_exts = $device->affinity_domains_ext
812		1044
813	Calls C<clGetDeviceInfo> with C<CL_DEVICE_AFFINITY_DOMAINS_EXT> and returns the result.	1045	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_AFFINITY_DOMAINS_EXT> and returns the result.
814		1046
815	=item $uint = $device->reference_count_ext	1047	=item $uint = $device->reference_count_ext
816		1048
817	Calls C<clGetDeviceInfo> with C<CL_DEVICE_REFERENCE_COUNT_EXT> and returns the result.	1049	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_REFERENCE_COUNT_EXT> and returns the result.
818		1050
819	=item @device_partition_property_exts = $device->partition_style_ext	1051	=item @device_partition_property_exts = $device->partition_style_ext
820		1052
821	Calls C<clGetDeviceInfo> with C<CL_DEVICE_PARTITION_STYLE_EXT> and returns the result.	1053	Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PARTITION_STYLE_EXT> and returns the result.
822		1054
823	=for gengetinfo end device	1055	=for gengetinfo end device
824		1056
825	=back	1057	=back
826		1058
827	=head2 THE OpenCL::Context CLASS	1059	=head2 THE OpenCL::Context CLASS
		1060
		1061	An OpenCL::Context is basically a container, or manager, for a number of
		1062	devices of a platform. It is used to create all sorts of secondary objects
		1063	such as buffers, queues, programs and so on.
		1064
		1065	All context creation functions and methods take a list of properties
		1066	(type-value pairs). All property values can be specified as integers -
		1067	some additionally support other types:
		1068
		1069	=over 4
		1070
		1071	=item OpenCL::CONTEXT_PLATFORM
		1072
		1073	Also accepts OpenCL::Platform objects.
		1074
		1075	=item OpenCL::GLX_DISPLAY_KHR
		1076
		1077	Also accepts C<undef>, in which case a deep and troubling hack is engaged
		1078	to find the current glx display (see L<GLX SUPPORT>).
		1079
		1080	=item OpenCL::GL_CONTEXT_KHR
		1081
		1082	Also accepts C<undef>, in which case a deep and troubling hack is engaged
		1083	to find the current glx context (see L<GLX SUPPORT>).
		1084
		1085	=back
828		1086
829	=over 4	1087	=over 4
830		1088
831	=item $prog = $ctx->build_program ($program, $options = "")	1089	=item $prog = $ctx->build_program ($program, $options = "")
832		1090
…		…
844	my ($self, $prog, $options) = @_;	1102	my ($self, $prog, $options) = @_;
845		1103
846	$prog = $self->program_with_source ($prog)	1104	$prog = $self->program_with_source ($prog)
847	unless ref $prog;	1105	unless ref $prog;
848		1106
		1107	eval { $prog->build (undef, $options); 1 }
		1108	or errno == BUILD_PROGRAM_FAILURE
		1109	or errno == INVALID_BINARY # workaround nvidia bug
		1110	or Carp::croak "OpenCL::Context->build_program: " . err2str;
		1111
		1112	# we check status for all devices
849	for my $dev ($self->devices) {	1113	for my $dev ($self->devices) {
850	eval { $prog->build ($dev, $options); 1 }	1114	$prog->build_status ($dev) == BUILD_SUCCESS
851	or Carp::croak "Building OpenCL program for device '" . $dev->name . "' failed:\n"	1115	or Carp::croak "Building OpenCL program for device '" . $dev->name . "' failed:\n"
852	. $prog->build_log ($dev);	1116	. $prog->build_log ($dev);
853	}	1117	}
854		1118
855	$prog	1119	$prog
856	}	1120	}
857		1121
…		…
874	=item $buf = $ctx->buffer ($flags, $len)	1138	=item $buf = $ctx->buffer ($flags, $len)
875		1139
876	Creates a new OpenCL::Buffer (actually OpenCL::BufferObj) object with the	1140	Creates a new OpenCL::Buffer (actually OpenCL::BufferObj) object with the
877	given flags and octet-size.	1141	given flags and octet-size.
878		1142
		1143	flags: OpenCL::MEM_READ_WRITE, OpenCL::MEM_WRITE_ONLY, OpenCL::MEM_READ_ONLY,
		1144	OpenCL::MEM_USE_HOST_PTR, OpenCL::MEM_ALLOC_HOST_PTR, OpenCL::MEM_COPY_HOST_PTR,
		1145	OpenCL::MEM_HOST_WRITE_ONLY, OpenCL::MEM_HOST_READ_ONLY, OpenCL::MEM_HOST_NO_ACCESS.
		1146
879	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateBuffer.html>	1147	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateBuffer.html>
880		1148
881	=item $buf = $ctx->buffer_sv ($flags, $data)	1149	=item $buf = $ctx->buffer_sv ($flags, $data)
882		1150
883	Creates a new OpenCL::Buffer (actually OpenCL::BufferObj) object and	1151	Creates a new OpenCL::Buffer (actually OpenCL::BufferObj) object and
884	initialise it with the given data values.	1152	initialise it with the given data values.
885		1153
886	=item $img = $ctx->image ($self, $flags, $channel_order, $channel_type, $type, $width, $height, $depth, $array_size = 0, $row_pitch = 0, $slice_pitch = 0, $num_mip_level = 0, $num_samples = 0, $*data = &PL_sv_undef)	1154	=item $img = $ctx->image ($self, $flags, $channel_order, $channel_type, $type, $width, $height, $depth = 0, $array_size = 0, $row_pitch = 0, $slice_pitch = 0, $num_mip_level = 0, $num_samples = 0, $*data = &PL_sv_undef)
887		1155
888	Creates a new OpenCL::Image object and optionally initialises it with	1156	Creates a new OpenCL::Image object and optionally initialises it with
889	the given data values.	1157	the given data values.
890		1158
		1159	channel_order: OpenCL::R, OpenCL::A, OpenCL::RG, OpenCL::RA, OpenCL::RGB,
		1160	OpenCL::RGBA, OpenCL::BGRA, OpenCL::ARGB, OpenCL::INTENSITY, OpenCL::LUMINANCE,
		1161	OpenCL::Rx, OpenCL::RGx, OpenCL::RGBx.
		1162
		1163	channel_type: OpenCL::SNORM_INT8, OpenCL::SNORM_INT16, OpenCL::UNORM_INT8,
		1164	OpenCL::UNORM_INT16, OpenCL::UNORM_SHORT_565, OpenCL::UNORM_SHORT_555,
		1165	OpenCL::UNORM_INT_101010, OpenCL::SIGNED_INT8, OpenCL::SIGNED_INT16,
		1166	OpenCL::SIGNED_INT32, OpenCL::UNSIGNED_INT8, OpenCL::UNSIGNED_INT16,
		1167	OpenCL::UNSIGNED_INT32, OpenCL::HALF_FLOAT, OpenCL::FLOAT.
		1168
		1169
		1170	type: OpenCL::MEM_OBJECT_BUFFER, OpenCL::MEM_OBJECT_IMAGE2D,
		1171	OpenCL::MEM_OBJECT_IMAGE3D, OpenCL::MEM_OBJECT_IMAGE2D_ARRAY,
		1172	OpenCL::MEM_OBJECT_IMAGE1D, OpenCL::MEM_OBJECT_IMAGE1D_ARRAY,
		1173	OpenCL::MEM_OBJECT_IMAGE1D_BUFFER.
		1174
891	L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCreateImage.html>	1175	L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCreateImage.html>
892		1176
893	=item $img = $ctx->image2d ($flags, $channel_order, $channel_type, $width, $height, $row_pitch = 0, $data = undef)	1177	=item $img = $ctx->image2d ($flags, $channel_order, $channel_type, $width, $height, $row_pitch = 0, $data = undef)
894		1178
895	Creates a new OpenCL::Image2D object and optionally initialises it with	1179	Creates a new OpenCL::Image2D object and optionally initialises it with
…		…
907	=item $buffer = $ctx->gl_buffer ($flags, $bufobj)	1191	=item $buffer = $ctx->gl_buffer ($flags, $bufobj)
908		1192
909	Creates a new OpenCL::Buffer (actually OpenCL::BufferObj) object that refers to the given	1193	Creates a new OpenCL::Buffer (actually OpenCL::BufferObj) object that refers to the given
910	OpenGL buffer object.	1194	OpenGL buffer object.
911		1195
		1196	flags: OpenCL::MEM_READ_WRITE, OpenCL::MEM_READ_ONLY, OpenCL::MEM_WRITE_ONLY.
		1197
912	http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateFromGLBuffer.html	1198	http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateFromGLBuffer.html
913		1199
914	=item $img = $ctx->gl_texture ($flags, $target, $miplevel, $texture)	1200	=item $img = $ctx->gl_texture ($flags, $target, $miplevel, $texture)
915		1201
916	Creates a new OpenCL::Image object that refers to the given OpenGL	1202	Creates a new OpenCL::Image object that refers to the given OpenGL
917	texture object or buffer.	1203	texture object or buffer.
918		1204
		1205	target: GL_TEXTURE_1D, GL_TEXTURE_1D_ARRAY, GL_TEXTURE_BUFFER,
		1206	GL_TEXTURE_2D, GL_TEXTURE_2D_ARRAY, GL_TEXTURE_3D,
		1207	GL_TEXTURE_CUBE_MAP_POSITIVE_X, GL_TEXTURE_CUBE_MAP_POSITIVE_Y,
		1208	GL_TEXTURE_CUBE_MAP_POSITIVE_Z, GL_TEXTURE_CUBE_MAP_NEGATIVE_X,
		1209	GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, GL_TEXTURE_CUBE_MAP_NEGATIVE_Z,
		1210	GL_TEXTURE_RECTANGLE/GL_TEXTURE_RECTANGLE_ARB.
		1211
919	http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCreateFromGLTexture.html	1212	http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCreateFromGLTexture.html
920		1213
921	=item $img = $ctx->gl_texture2d ($flags, $target, $miplevel, $texture)	1214	=item $img = $ctx->gl_texture2d ($flags, $target, $miplevel, $texture)
922		1215
923	Creates a new OpenCL::Image2D object that refers to the given OpenGL	1216	Creates a new OpenCL::Image2D object that refers to the given OpenGL
…		…
948		1241
949	=item $sampler = $ctx->sampler ($normalized_coords, $addressing_mode, $filter_mode)	1242	=item $sampler = $ctx->sampler ($normalized_coords, $addressing_mode, $filter_mode)
950		1243
951	Creates a new OpenCL::Sampler object.	1244	Creates a new OpenCL::Sampler object.
952		1245
		1246	addressing_mode: OpenCL::ADDRESS_NONE, OpenCL::ADDRESS_CLAMP_TO_EDGE,
		1247	OpenCL::ADDRESS_CLAMP, OpenCL::ADDRESS_REPEAT, OpenCL::ADDRESS_MIRRORED_REPEAT.
		1248
		1249	filter_mode: OpenCL::FILTER_NEAREST, OpenCL::FILTER_LINEAR.
		1250
953	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateSampler.html>	1251	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateSampler.html>
954		1252
955	=item $program = $ctx->program_with_source ($string)	1253	=item $program = $ctx->program_with_source ($string)
956		1254
957	Creates a new OpenCL::Program object from the given source code.	1255	Creates a new OpenCL::Program object from the given source code.
958		1256
959	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateProgramWithSource.html>	1257	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateProgramWithSource.html>
960		1258
		1259	=item ($program, \@status) = $ctx->program_with_binary (\@devices, \@binaries)
		1260
		1261	Creates a new OpenCL::Program object from the given binaries.
		1262
		1263	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateProgramWithBinary.html>
		1264
		1265	Example: clone an existing program object that contains a successfully
		1266	compiled program, no matter how useless this is.
		1267
		1268	my $clone = $ctx->program_with_binary ([$prog->devices], [$prog->binaries]);
		1269
		1270	=item $program = $ctx->program_with_built_in_kernels (\@devices, $kernel_names)
		1271
		1272	Creates a new OpenCL::Program object from the given built-in kernel names.
		1273
		1274	L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCreateProgramWithBuiltInKernels.html>
		1275
961	=item $packed_value = $ctx->info ($name)	1276	=item $packed_value = $ctx->info ($name)
962		1277
963	See C<< $platform->info >> for details.	1278	See C<< $platform->info >> for details.
964		1279
965	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html>	1280	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html>
966		1281
967	=for gengetinfo begin context	1282	=for gengetinfo begin context
968		1283
969	=item $uint = $context->reference_count	1284	=item $uint = $context->reference_count
970		1285
971	Calls C<clGetContextInfo> with C<CL_CONTEXT_REFERENCE_COUNT> and returns the result.	1286	Calls C<clGetContextInfo> with C<OpenCL::CONTEXT_REFERENCE_COUNT> and returns the result.
972		1287
973	=item @devices = $context->devices	1288	=item @devices = $context->devices
974		1289
975	Calls C<clGetContextInfo> with C<CL_CONTEXT_DEVICES> and returns the result.	1290	Calls C<clGetContextInfo> with C<OpenCL::CONTEXT_DEVICES> and returns the result.
976		1291
977	=item @property_ints = $context->properties	1292	=item @property_ints = $context->properties
978		1293
979	Calls C<clGetContextInfo> with C<CL_CONTEXT_PROPERTIES> and returns the result.	1294	Calls C<clGetContextInfo> with C<OpenCL::CONTEXT_PROPERTIES> and returns the result.
980		1295
981	=item $uint = $context->num_devices	1296	=item $uint = $context->num_devices
982		1297
983	Calls C<clGetContextInfo> with C<CL_CONTEXT_NUM_DEVICES> and returns the result.	1298	Calls C<clGetContextInfo> with C<OpenCL::CONTEXT_NUM_DEVICES> and returns the result.
984		1299
985	=for gengetinfo end context	1300	=for gengetinfo end context
986		1301
987	=back	1302	=back
988		1303
989	=head2 THE OpenCL::Queue CLASS	1304	=head2 THE OpenCL::Queue CLASS
990		1305
991	An OpenCL::Queue represents an execution queue for OpenCL. You execute	1306	An OpenCL::Queue represents an execution queue for OpenCL. You execute
992	requests by calling their respective C<enqueue_xxx> method and waitinf for	1307	requests by calling their respective method and waiting for it to complete
993	it to complete in some way.	1308	in some way.
994		1309
995	All the enqueue methods return an event object that can be used to wait	1310	Most methods that enqueue some request return an event object that can
996	for completion, unless the method is called in void context, in which case	1311	be used to wait for completion (optionally using a callback), unless
997	no event object is created.	1312	the method is called in void context, in which case no event object is
		1313	created.
998		1314
999	They also allow you to specify any number of other event objects that this	1315	They also allow you to specify any number of other event objects that this
1000	request has to wait for before it starts executing, by simply passing the	1316	request has to wait for before it starts executing, by simply passing the
1001	event objects as extra parameters to the enqueue methods. To simplify	1317	event objects as extra parameters to the enqueue methods. To simplify
1002	program design, this module ignores any C<undef> values in the list of	1318	program design, this module ignores any C<undef> values in the list of
1003	events. This makes it possible to code operations such as this, without	1319	events. This makes it possible to code operations such as this, without
1004	having to put a valid event object into C<$event> first:	1320	having to put a valid event object into C<$event> first:
1005		1321
1006	$event = $queue->enqueue_xxx (..., $event);	1322	$event = $queue->xxx (..., $event);
1007		1323
1008	Queues execute in-order by default, without any parallelism, so in most	1324	Queues execute in-order by default, without any parallelism, so in most
1009	cases (i.e. you use only one queue) it's not necessary to wait for or	1325	cases (i.e. you use only one queue) it's not necessary to wait for or
1010	create event objects, althoguh an our of order queue is often a bit	1326	create event objects, althoguh an our of order queue is often a bit
1011	faster.	1327	faster.
1012		1328
1013	=over 4	1329	=over 4
1014		1330
1015	=item $ev = $queue->enqueue_read_buffer ($buffer, $blocking, $offset, $len, $data, $wait_events...)	1331	=item $ev = $queue->read_buffer ($buffer, $blocking, $offset, $len, $data, $wait_events...)
1016		1332
1017	Reads data from buffer into the given string.	1333	Reads data from buffer into the given string.
1018		1334
1019	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadBuffer.html>	1335	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadBuffer.html>
1020		1336
1021	=item $ev = $queue->enqueue_write_buffer ($buffer, $blocking, $offset, $data, $wait_events...)	1337	=item $ev = $queue->write_buffer ($buffer, $blocking, $offset, $data, $wait_events...)
1022		1338
1023	Writes data to buffer from the given string.	1339	Writes data to buffer from the given string.
1024		1340
1025	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteBuffer.html>	1341	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteBuffer.html>
1026		1342
1027	=item $ev = $queue->enqueue_copy_buffer ($src, $dst, $src_offset, $dst_offset, $len, $wait_events...)	1343	=item $ev = $queue->copy_buffer ($src, $dst, $src_offset, $dst_offset, $len, $wait_events...)
1028		1344
1029	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBuffer.html>	1345	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBuffer.html>
1030		1346
1031	=item $ev = $queue->enqueue_read_buffer_rect (OpenCL::Memory buf, cl_bool blocking, $buf_x, $buf_y, $buf_z, $host_x, $host_y, $host_z, $width, $height, $depth, $buf_row_pitch, $buf_slice_pitch, $host_row_pitch, $host_slice_pitch, $data, $wait_events...)	1347	=item $ev = $queue->read_buffer_rect (OpenCL::Memory buf, cl_bool blocking, $buf_x, $buf_y, $buf_z, $host_x, $host_y, $host_z, $width, $height, $depth, $buf_row_pitch, $buf_slice_pitch, $host_row_pitch, $host_slice_pitch, $data, $wait_events...)
1032		1348
1033	http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadBufferRect.html	1349	http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadBufferRect.html
1034		1350
1035	=item $ev = $queue->enqueue_write_buffer_rect (OpenCL::Memory buf, cl_bool blocking, $buf_x, $buf_y, $buf_z, $host_x, $host_y, $host_z, $width, $height, $depth, $buf_row_pitch, $buf_slice_pitch, $host_row_pitch, $host_slice_pitch, $data, $wait_events...)	1351	=item $ev = $queue->write_buffer_rect (OpenCL::Memory buf, cl_bool blocking, $buf_x, $buf_y, $buf_z, $host_x, $host_y, $host_z, $width, $height, $depth, $buf_row_pitch, $buf_slice_pitch, $host_row_pitch, $host_slice_pitch, $data, $wait_events...)
1036		1352
1037	http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteBufferRect.html	1353	http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteBufferRect.html
1038		1354
1039	=item $ev = $queue->enqueue_read_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...)
1040
1041	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferRect.html>
1042
1043	=item $ev = $queue->enqueue_copy_buffer_to_image ($src_buffer, $dst_image, $src_offset, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $wait_events...)	1355	=item $ev = $queue->copy_buffer_to_image ($src_buffer, $dst_image, $src_offset, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $wait_events...)
		1356
		1357	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferToImage.html>
		1358
		1359	=item $ev = $queue->read_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...)
		1360
		1361	C<$row_pitch> (and C<$slice_pitch>) can be C<0>, in which case the OpenCL
		1362	module uses the image width (and height) to supply default values.
1044		1363
1045	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadImage.html>	1364	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadImage.html>
1046		1365
1047	=item $ev = $queue->enqueue_write_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...)	1366	=item $ev = $queue->write_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...)
1048		1367
		1368	C<$row_pitch> (and C<$slice_pitch>) can be C<0>, in which case the OpenCL
		1369	module uses the image width (and height) to supply default values.
1049	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteImage.html>	1370	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteImage.html>
1050		1371
1051	=item $ev = $queue->enqueue_copy_image ($src_image, $dst_image, $src_x, $src_y, $src_z, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $wait_events...)	1372	=item $ev = $queue->copy_image ($src_image, $dst_image, $src_x, $src_y, $src_z, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $wait_events...)
1052		1373
1053	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImage.html>	1374	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImage.html>
1054		1375
1055	=item $ev = $queue->enqueue_copy_image_to_buffer ($src_image, $dst_image, $src_x, $src_y, $src_z, $width, $height, $depth, $dst_offset, $wait_events...)	1376	=item $ev = $queue->copy_image_to_buffer ($src_image, $dst_image, $src_x, $src_y, $src_z, $width, $height, $depth, $dst_offset, $wait_events...)
1056		1377
1057	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImageToBuffer.html>	1378	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImageToBuffer.html>
1058		1379
1059	=item $ev = $queue->enqueue_copy_buffer_rect ($src, $dst, $src_x, $src_y, $src_z, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $src_row_pitch, $src_slice_pitch, $dst_row_pitch, $dst_slice_pitch, $wait_event...)	1380	=item $ev = $queue->copy_buffer_rect ($src, $dst, $src_x, $src_y, $src_z, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $src_row_pitch, $src_slice_pitch, $dst_row_pitch, $dst_slice_pitch, $wait_event...)
1060		1381
1061	Yeah.	1382	Yeah.
1062		1383
1063	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferToImage.html>.	1384	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferToImage.html>.
1064		1385
1065	=item $ev = $queue->enqueue_fill_buffer ($mem, $pattern, $offset, $size, ...)	1386	=item $ev = $queue->fill_buffer ($mem, $pattern, $offset, $size, ...)
1066		1387
1067	Fills the given buffer object with repeated applications of C<$pattern>,	1388	Fills the given buffer object with repeated applications of C<$pattern>,
1068	starting at C<$offset> for C<$size> octets.	1389	starting at C<$offset> for C<$size> octets.
1069		1390
1070	L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clEnqueueFillBuffer.html>	1391	L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clEnqueueFillBuffer.html>
1071		1392
1072	=item $ev = $queue->enqueue_fill_image ($img, $r, $g, $b, $a, $x, $y, $z, $width, $height, $depth, ...)	1393	=item $ev = $queue->fill_image ($img, $r, $g, $b, $a, $x, $y, $z, $width, $height, $depth, ...)
1073		1394
1074	Fills the given image area with the given rgba colour components. The	1395	Fills the given image area with the given rgba colour components. The
1075	components are normally floating point values between C<0> and C<1>,	1396	components are normally floating point values between C<0> and C<1>,
1076	except when the image channel data type is a signe dor unsigned	1397	except when the image channel data type is a signe dor unsigned
1077	unnormalised format, in which case the range is determined by the format.	1398	unnormalised format, in which case the range is determined by the format.
1078		1399
1079	L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clEnqueueFillImage.html>	1400	L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clEnqueueFillImage.html>
1080		1401
1081	=item $ev = $queue->enqueue_task ($kernel, $wait_events...)	1402	=item $ev = $queue->task ($kernel, $wait_events...)
1082		1403
1083	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueTask.html>	1404	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueTask.html>
1084		1405
1085	=item $ev = $queue->enqueue_nd_range_kernel ($kernel, @$global_work_offset, @$global_work_size, @$local_work_size, $wait_events...)	1406	=item $ev = $queue->nd_range_kernel ($kernel, \@global_work_offset, \@global_work_size, \@local_work_size, $wait_events...)
1086		1407
1087	Enqueues a kernel execution.	1408	Enqueues a kernel execution.
1088		1409
1089	@$global_work_size must be specified as a reference to an array of	1410	\@global_work_size must be specified as a reference to an array of
1090	integers specifying the work sizes (element counts).	1411	integers specifying the work sizes (element counts).
1091		1412
1092	@$global_work_offset must be either C<undef> (in which case all offsets	1413	\@global_work_offset must be either C<undef> (in which case all offsets
1093	are C<0>), or a reference to an array of work offsets, with the same number	1414	are C<0>), or a reference to an array of work offsets, with the same number
1094	of elements as @$global_work_size.	1415	of elements as \@global_work_size.
1095		1416
1096	@$local_work_size must be either C<undef> (in which case the	1417	\@local_work_size must be either C<undef> (in which case the
1097	implementation is supposed to choose good local work sizes), or a	1418	implementation is supposed to choose good local work sizes), or a
1098	reference to an array of local work sizes, with the same number of	1419	reference to an array of local work sizes, with the same number of
1099	elements as @$global_work_size.	1420	elements as \@global_work_size.
1100		1421
1101	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueNDRangeKernel.html>	1422	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueNDRangeKernel.html>
1102		1423
		1424	=item $ev = $queue->migrate_mem_objects (\@mem_objects, $flags, $wait_events...)
		1425
		1426	Migrates a number of OpenCL::Memory objects to or from the device.
		1427
		1428	flags: OpenCL::MIGRATE_MEM_OBJECT_HOST, OpenCL::MIGRATE_MEM_OBJECT_CONTENT_UNDEFINED
		1429
		1430	L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clEnqueueMigrateMemObjects.html>
		1431
1103	=item $ev = $queue->enqueue_acquire_gl_objects ([object, ...], $wait_events...)	1432	=item $ev = $queue->acquire_gl_objects ([object, ...], $wait_events...)
1104		1433
1105	Enqueues a list (an array-ref of OpenCL::Memory objects) to be acquired	1434	Enqueues a list (an array-ref of OpenCL::Memory objects) to be acquired
1106	for subsequent OpenCL usage.	1435	for subsequent OpenCL usage.
1107		1436
1108	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueAcquireGLObjects.html>	1437	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueAcquireGLObjects.html>
1109		1438
1110	=item $ev = $queue->enqueue_release_gl_objects ([object, ...], $wait_events...)	1439	=item $ev = $queue->release_gl_objects ([object, ...], $wait_events...)
1111		1440
1112	Enqueues a list (an array-ref of OpenCL::Memory objects) to be released	1441	Enqueues a list (an array-ref of OpenCL::Memory objects) to be released
1113	for subsequent OpenGL usage.	1442	for subsequent OpenGL usage.
1114		1443
1115	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReleaseGLObjects.html>	1444	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReleaseGLObjects.html>
1116		1445
1117	=item $ev = $queue->enqueue_wait_for_events ($wait_events...)	1446	=item $ev = $queue->wait_for_events ($wait_events...)
1118		1447
1119	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWaitForEvents.html>	1448	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWaitForEvents.html>
1120		1449
1121	=item $ev = $queue->enqueue_marker ($wait_events...)	1450	=item $ev = $queue->marker ($wait_events...)
1122		1451
1123	L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clEnqueueMarkerWithWaitList.html>	1452	L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clEnqueueMarkerWithWaitList.html>
1124		1453
1125	=item $ev = $queue->enqueue_barrier ($wait_events...)	1454	=item $ev = $queue->barrier ($wait_events...)
1126		1455
1127	L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clEnqueueBarrierWithWaitList.html>	1456	L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clEnqueueBarrierWithWaitList.html>
1128		1457
1129	=item $queue->flush	1458	=item $queue->flush
1130		1459
…		…
1142		1471
1143	=for gengetinfo begin command_queue	1472	=for gengetinfo begin command_queue
1144		1473
1145	=item $ctx = $command_queue->context	1474	=item $ctx = $command_queue->context
1146		1475
1147	Calls C<clGetCommandQueueInfo> with C<CL_QUEUE_CONTEXT> and returns the result.	1476	Calls C<clGetCommandQueueInfo> with C<OpenCL::QUEUE_CONTEXT> and returns the result.
1148		1477
1149	=item $device = $command_queue->device	1478	=item $device = $command_queue->device
1150		1479
1151	Calls C<clGetCommandQueueInfo> with C<CL_QUEUE_DEVICE> and returns the result.	1480	Calls C<clGetCommandQueueInfo> with C<OpenCL::QUEUE_DEVICE> and returns the result.
1152		1481
1153	=item $uint = $command_queue->reference_count	1482	=item $uint = $command_queue->reference_count
1154		1483
1155	Calls C<clGetCommandQueueInfo> with C<CL_QUEUE_REFERENCE_COUNT> and returns the result.	1484	Calls C<clGetCommandQueueInfo> with C<OpenCL::QUEUE_REFERENCE_COUNT> and returns the result.
1156		1485
1157	=item $command_queue_properties = $command_queue->properties	1486	=item $command_queue_properties = $command_queue->properties
1158		1487
1159	Calls C<clGetCommandQueueInfo> with C<CL_QUEUE_PROPERTIES> and returns the result.	1488	Calls C<clGetCommandQueueInfo> with C<OpenCL::QUEUE_PROPERTIES> and returns the result.
1160		1489
1161	=for gengetinfo end command_queue	1490	=for gengetinfo end command_queue
		1491
		1492	=back
		1493
		1494	=head3 MEMORY MAPPED BUFFERS
		1495
		1496	OpenCL allows you to map buffers and images to host memory (read: perl
		1497	scalars). This is done much like reading or copying a buffer, by enqueuing
		1498	a map or unmap operation on the command queue.
		1499
		1500	The map operations return an C<OpenCL::Mapped> object - see L<THE
		1501	OpenCL::Mapped CLASS> section for details on what to do with these
		1502	objects.
		1503
		1504	The object will be unmapped automatically when the mapped object is
		1505	destroyed (you can use a barrier to make sure the unmap has finished,
		1506	before using the buffer in a kernel), but you can also enqueue an unmap
		1507	operation manually.
		1508
		1509	=over 4
		1510
		1511	=item $mapped_buffer = $queue->map_buffer ($buf, $blocking=1, $map_flags=OpenCL::MAP_READ|OpenCL::MAP_WRITE, $offset=0, $size=undef, $wait_events...)
		1512
		1513	Maps the given buffer into host memory and returns an
		1514	C<OpenCL::MappedBuffer> object. If C<$size> is specified as undef, then
		1515	the map will extend to the end of the buffer.
		1516
		1517	map_flags: OpenCL::MAP_READ, OpenCL::MAP_WRITE, OpenCL::MAP_WRITE_INVALIDATE_REGION.
		1518
		1519	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueMapBuffer.html>
		1520
		1521	Example: map the buffer $buf fully and replace the first 4 bytes by "abcd", then unmap.
		1522
		1523	{
		1524	my $mapped = $queue->map_buffer ($buf, 1, OpenCL::MAP_WRITE);
		1525	substr $$mapped, 0, 4, "abcd";
		1526	} # asynchronously unmap because $mapped is destroyed
		1527
		1528	=item $mapped_image = $queue->map_image ($img, $blocking=1, $map_flags=OpenCL::MAP_READ|OpenCL::MAP_WRITE, $x=0, $y=0, $z=0, $width=undef, $height=undef, $depth=undef, $wait_events...)
		1529
		1530	Maps the given image area into host memory and return an
		1531	C<OpenCL::MappedImage> object.
		1532
		1533	If any of C<$width>, C<$height> and/or C<$depth> are C<undef> then they
		1534	will be replaced by the maximum possible value.
		1535
		1536	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueMapImage.html>
		1537
		1538	Example: map an image (with OpenCL::UNSIGNED_INT8 channel type) and set
		1539	the first channel of the leftmost column to 5, then explicitly unmap
		1540	it. You are not necessarily meant to do it this way, this example just
		1541	shows you the accessors to use :)
		1542
		1543	my $mapped = $queue->map_image ($image, 1, OpenCL::MAP_WRITE);
		1544
		1545	$mapped->set ($_ * $mapped->row_pitch, pack "C", 5)
		1546	for 0..$image->height;
		1547
		1548	$mapped->unmap;.
		1549	$mapped->wait; # only needed for out of order queues normally
		1550
		1551	=item $ev = $queue->unmap ($mapped, $wait_events...)
		1552
		1553	Unmaps the data from host memory. You must not call any methods that
		1554	modify the data, or modify the data scalar directly, after calling this
		1555	method.
		1556
		1557	The mapped event object will always be passed as part of the
		1558	$wait_events. The mapped event object will be replaced by the new event
		1559	object that this request creates.
1162		1560
1163	=back	1561	=back
1164		1562
1165	=head2 THE OpenCL::Memory CLASS	1563	=head2 THE OpenCL::Memory CLASS
1166		1564
…		…
1177		1575
1178	=for gengetinfo begin mem	1576	=for gengetinfo begin mem
1179		1577
1180	=item $mem_object_type = $mem->type	1578	=item $mem_object_type = $mem->type
1181		1579
1182	Calls C<clGetMemObjectInfo> with C<CL_MEM_TYPE> and returns the result.	1580	Calls C<clGetMemObjectInfo> with C<OpenCL::MEM_TYPE> and returns the result.
1183		1581
1184	=item $mem_flags = $mem->flags	1582	=item $mem_flags = $mem->flags
1185		1583
1186	Calls C<clGetMemObjectInfo> with C<CL_MEM_FLAGS> and returns the result.	1584	Calls C<clGetMemObjectInfo> with C<OpenCL::MEM_FLAGS> and returns the result.
1187		1585
1188	=item $int = $mem->size	1586	=item $int = $mem->size
1189		1587
1190	Calls C<clGetMemObjectInfo> with C<CL_MEM_SIZE> and returns the result.	1588	Calls C<clGetMemObjectInfo> with C<OpenCL::MEM_SIZE> and returns the result.
1191		1589
1192	=item $ptr_value = $mem->host_ptr	1590	=item $ptr_value = $mem->host_ptr
1193		1591
1194	Calls C<clGetMemObjectInfo> with C<CL_MEM_HOST_PTR> and returns the result.	1592	Calls C<clGetMemObjectInfo> with C<OpenCL::MEM_HOST_PTR> and returns the result.
1195		1593
1196	=item $uint = $mem->map_count	1594	=item $uint = $mem->map_count
1197		1595
1198	Calls C<clGetMemObjectInfo> with C<CL_MEM_MAP_COUNT> and returns the result.	1596	Calls C<clGetMemObjectInfo> with C<OpenCL::MEM_MAP_COUNT> and returns the result.
1199		1597
1200	=item $uint = $mem->reference_count	1598	=item $uint = $mem->reference_count
1201		1599
1202	Calls C<clGetMemObjectInfo> with C<CL_MEM_REFERENCE_COUNT> and returns the result.	1600	Calls C<clGetMemObjectInfo> with C<OpenCL::MEM_REFERENCE_COUNT> and returns the result.
1203		1601
1204	=item $ctx = $mem->context	1602	=item $ctx = $mem->context
1205		1603
1206	Calls C<clGetMemObjectInfo> with C<CL_MEM_CONTEXT> and returns the result.	1604	Calls C<clGetMemObjectInfo> with C<OpenCL::MEM_CONTEXT> and returns the result.
1207		1605
1208	=item $mem = $mem->associated_memobject	1606	=item $mem = $mem->associated_memobject
1209		1607
1210	Calls C<clGetMemObjectInfo> with C<CL_MEM_ASSOCIATED_MEMOBJECT> and returns the result.	1608	Calls C<clGetMemObjectInfo> with C<OpenCL::MEM_ASSOCIATED_MEMOBJECT> and returns the result.
1211		1609
1212	=item $int = $mem->offset	1610	=item $int = $mem->offset
1213		1611
1214	Calls C<clGetMemObjectInfo> with C<CL_MEM_OFFSET> and returns the result.	1612	Calls C<clGetMemObjectInfo> with C<OpenCL::MEM_OFFSET> and returns the result.
1215		1613
1216	=for gengetinfo end mem	1614	=for gengetinfo end mem
1217		1615
1218	=item ($type, $name) = $mem->gl_object_info	1616	=item ($type, $name) = $mem->gl_object_info
1219		1617
…		…
1253	OpenCL::Image1DArray, OpenCL::Image1DBuffer, OpenCL::Image2D,	1651	OpenCL::Image1DArray, OpenCL::Image1DBuffer, OpenCL::Image2D,
1254	OpenCL::Image2DArray and OpenCL::Image3D.	1652	OpenCL::Image2DArray and OpenCL::Image3D.
1255		1653
1256	=over 4	1654	=over 4
1257		1655
1258	=item $packed_value = $ev->image_info ($name)	1656	=item $packed_value = $image->image_info ($name)
1259		1657
1260	See C<< $platform->info >> for details.	1658	See C<< $platform->info >> for details.
1261		1659
1262	The reason this method is not called C<info> is that there already is an	1660	The reason this method is not called C<info> is that there already is an
1263	C<< ->info >> method inherited from C<OpenCL::Memory>.	1661	C<< ->info >> method inherited from C<OpenCL::Memory>.
1264		1662
1265	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetImageInfo.html>	1663	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetImageInfo.html>
1266		1664
		1665	=item ($channel_order, $channel_data_type) = $image->format
		1666
		1667	Returns the channel order and type used to create the image by calling
		1668	C<clGetImageInfo> with C<CL_IMAGE_FORMAT>.
		1669
1267	=for gengetinfo begin image	1670	=for gengetinfo begin image
1268		1671
1269	=item $int = $image->element_size	1672	=item $int = $image->element_size
1270		1673
1271	Calls C<clGetImageInfo> with C<CL_IMAGE_ELEMENT_SIZE> and returns the result.	1674	Calls C<clGetImageInfo> with C<OpenCL::IMAGE_ELEMENT_SIZE> and returns the result.
1272		1675
1273	=item $int = $image->row_pitch	1676	=item $int = $image->row_pitch
1274		1677
1275	Calls C<clGetImageInfo> with C<CL_IMAGE_ROW_PITCH> and returns the result.	1678	Calls C<clGetImageInfo> with C<OpenCL::IMAGE_ROW_PITCH> and returns the result.
1276		1679
1277	=item $int = $image->slice_pitch	1680	=item $int = $image->slice_pitch
1278		1681
1279	Calls C<clGetImageInfo> with C<CL_IMAGE_SLICE_PITCH> and returns the result.	1682	Calls C<clGetImageInfo> with C<OpenCL::IMAGE_SLICE_PITCH> and returns the result.
1280		1683
1281	=item $int = $image->width	1684	=item $int = $image->width
1282		1685
1283	Calls C<clGetImageInfo> with C<CL_IMAGE_WIDTH> and returns the result.	1686	Calls C<clGetImageInfo> with C<OpenCL::IMAGE_WIDTH> and returns the result.
1284		1687
1285	=item $int = $image->height	1688	=item $int = $image->height
1286		1689
1287	Calls C<clGetImageInfo> with C<CL_IMAGE_HEIGHT> and returns the result.	1690	Calls C<clGetImageInfo> with C<OpenCL::IMAGE_HEIGHT> and returns the result.
1288		1691
1289	=item $int = $image->depth	1692	=item $int = $image->depth
1290		1693
1291	Calls C<clGetImageInfo> with C<CL_IMAGE_DEPTH> and returns the result.	1694	Calls C<clGetImageInfo> with C<OpenCL::IMAGE_DEPTH> and returns the result.
1292		1695
1293	=for gengetinfo end image	1696	=for gengetinfo end image
1294		1697
1295	=for gengetinfo begin gl_texture	1698	=for gengetinfo begin gl_texture
1296		1699
1297	=item $GLenum = $gl_texture->target	1700	=item $GLenum = $gl_texture->target
1298		1701
1299	Calls C<clGetGLTextureInfo> with C<CL_GL_TEXTURE_TARGET> and returns the result.	1702	Calls C<clGetGLTextureInfo> with C<OpenCL::GL_TEXTURE_TARGET> and returns the result.
1300		1703
1301	=item $GLint = $gl_texture->gl_mipmap_level	1704	=item $GLint = $gl_texture->gl_mipmap_level
1302		1705
1303	Calls C<clGetGLTextureInfo> with C<CL_GL_MIPMAP_LEVEL> and returns the result.	1706	Calls C<clGetGLTextureInfo> with C<OpenCL::GL_MIPMAP_LEVEL> and returns the result.
1304		1707
1305	=for gengetinfo end gl_texture	1708	=for gengetinfo end gl_texture
1306		1709
1307	=back	1710	=back
1308		1711
…		…
1318		1721
1319	=for gengetinfo begin sampler	1722	=for gengetinfo begin sampler
1320		1723
1321	=item $uint = $sampler->reference_count	1724	=item $uint = $sampler->reference_count
1322		1725
1323	Calls C<clGetSamplerInfo> with C<CL_SAMPLER_REFERENCE_COUNT> and returns the result.	1726	Calls C<clGetSamplerInfo> with C<OpenCL::SAMPLER_REFERENCE_COUNT> and returns the result.
1324		1727
1325	=item $ctx = $sampler->context	1728	=item $ctx = $sampler->context
1326		1729
1327	Calls C<clGetSamplerInfo> with C<CL_SAMPLER_CONTEXT> and returns the result.	1730	Calls C<clGetSamplerInfo> with C<OpenCL::SAMPLER_CONTEXT> and returns the result.
1328		1731
1329	=item $addressing_mode = $sampler->normalized_coords	1732	=item $addressing_mode = $sampler->normalized_coords
1330		1733
1331	Calls C<clGetSamplerInfo> with C<CL_SAMPLER_NORMALIZED_COORDS> and returns the result.	1734	Calls C<clGetSamplerInfo> with C<OpenCL::SAMPLER_NORMALIZED_COORDS> and returns the result.
1332		1735
1333	=item $filter_mode = $sampler->addressing_mode	1736	=item $filter_mode = $sampler->addressing_mode
1334		1737
1335	Calls C<clGetSamplerInfo> with C<CL_SAMPLER_ADDRESSING_MODE> and returns the result.	1738	Calls C<clGetSamplerInfo> with C<OpenCL::SAMPLER_ADDRESSING_MODE> and returns the result.
1336		1739
1337	=item $boolean = $sampler->filter_mode	1740	=item $boolean = $sampler->filter_mode
1338		1741
1339	Calls C<clGetSamplerInfo> with C<CL_SAMPLER_FILTER_MODE> and returns the result.	1742	Calls C<clGetSamplerInfo> with C<OpenCL::SAMPLER_FILTER_MODE> and returns the result.
1340		1743
1341	=for gengetinfo end sampler	1744	=for gengetinfo end sampler
1342		1745
1343	=back	1746	=back
1344		1747
1345	=head2 THE OpenCL::Program CLASS	1748	=head2 THE OpenCL::Program CLASS
1346		1749
1347	=over 4	1750	=over 4
1348		1751
1349	=item $program->build ($device, $options = "")	1752	=item $program->build (\@devices = undef, $options = "", $cb->($program) = undef)
1350		1753
1351	Tries to build the program with the given options. See also the	1754	Tries to build the program with the given options. See also the
1352	C<$ctx->build> convenience function.	1755	C<$ctx->build> convenience function.
1353		1756
		1757	If a callback is specified, then it will be called when compilation is
		1758	finished. Note that many OpenCL implementations block your program while
		1759	compiling whether you use a callback or not. See C<build_async> if you
		1760	want to make sure the build is done in the background.
		1761
		1762	Note that some OpenCL implementations act up badly, and don't call the
		1763	callback in some error cases (but call it in others). This implementation
		1764	assumes the callback will always be called, and leaks memory if this is
		1765	not so. So best make sure you don't pass in invalid values.
		1766
		1767	Some implementations fail with C<OpenCL::INVALID_BINARY> when the
		1768	compilation state is successful but some later stage fails.
		1769
		1770	options: C<-D name>, C<-D name=definition>, C<-I dir>,
		1771	C<-cl-single-precision-constant>, C<-cl-denorms-are-zero>,
		1772	C<-cl-fp32-correctly-rounded-divide-sqrt>, C<-cl-opt-disable>,
		1773	C<-cl-mad-enable>, C<-cl-no-signed-zeros>, C<-cl-unsafe-math-optimizations>,
		1774	C<-cl-finite-math-only>, C<-cl-fast-relaxed-math>,
		1775	C<-w>, C<-Werror>, C<-cl-std=CL1.1/CL1.2>, C<-cl-kernel-arg-info>,
		1776	C<-create-library>, C<-enable-link-options>.
		1777
1354	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clBuildProgram.html>	1778	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clBuildProgram.html>
		1779
		1780	=item $program->build_async (\@devices = undef, $options = "", $cb->($program) = undef)
		1781
		1782	Similar to C<< ->build >>, except it starts a thread, and never fails (you
		1783	need to check the compilation status form the callback, or by polling).
		1784
		1785	build_status: OpenCL::BUILD_SUCCESS, OpenCL::BUILD_NONE,
		1786	OpenCL::BUILD_ERROR, OpenCL::BUILD_IN_PROGRESS.
1355		1787
1356	=item $packed_value = $program->build_info ($device, $name)	1788	=item $packed_value = $program->build_info ($device, $name)
1357		1789
1358	Similar to C<< $platform->info >>, but returns build info for a previous	1790	Similar to C<< $platform->info >>, but returns build info for a previous
1359	build attempt for the given device.	1791	build attempt for the given device.
…		…
1375		1807
1376	=for gengetinfo begin program_build	1808	=for gengetinfo begin program_build
1377		1809
1378	=item $build_status = $program->build_status ($device)	1810	=item $build_status = $program->build_status ($device)
1379		1811
1380	Calls C<clGetProgramBuildInfo> with C<CL_PROGRAM_BUILD_STATUS> and returns the result.	1812	Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_STATUS> and returns the result.
1381		1813
1382	=item $string = $program->build_options ($device)	1814	=item $string = $program->build_options ($device)
1383		1815
1384	Calls C<clGetProgramBuildInfo> with C<CL_PROGRAM_BUILD_OPTIONS> and returns the result.	1816	Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_OPTIONS> and returns the result.
1385		1817
1386	=item $string = $program->build_log ($device)	1818	=item $string = $program->build_log ($device)
1387		1819
1388	Calls C<clGetProgramBuildInfo> with C<CL_PROGRAM_BUILD_LOG> and returns the result.	1820	Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_LOG> and returns the result.
1389		1821
1390	=for gengetinfo end program_build	1822	=for gengetinfo end program_build
1391		1823
1392	=item $packed_value = $program->info ($name)	1824	=item $packed_value = $program->info ($name)
1393		1825
…		…
1397		1829
1398	=for gengetinfo begin program	1830	=for gengetinfo begin program
1399		1831
1400	=item $uint = $program->reference_count	1832	=item $uint = $program->reference_count
1401		1833
1402	Calls C<clGetProgramInfo> with C<CL_PROGRAM_REFERENCE_COUNT> and returns the result.	1834	Calls C<clGetProgramInfo> with C<OpenCL::PROGRAM_REFERENCE_COUNT> and returns the result.
1403		1835
1404	=item $ctx = $program->context	1836	=item $ctx = $program->context
1405		1837
1406	Calls C<clGetProgramInfo> with C<CL_PROGRAM_CONTEXT> and returns the result.	1838	Calls C<clGetProgramInfo> with C<OpenCL::PROGRAM_CONTEXT> and returns the result.
1407		1839
1408	=item $uint = $program->num_devices	1840	=item $uint = $program->num_devices
1409		1841
1410	Calls C<clGetProgramInfo> with C<CL_PROGRAM_NUM_DEVICES> and returns the result.	1842	Calls C<clGetProgramInfo> with C<OpenCL::PROGRAM_NUM_DEVICES> and returns the result.
1411		1843
1412	=item @devices = $program->devices	1844	=item @devices = $program->devices
1413		1845
1414	Calls C<clGetProgramInfo> with C<CL_PROGRAM_DEVICES> and returns the result.	1846	Calls C<clGetProgramInfo> with C<OpenCL::PROGRAM_DEVICES> and returns the result.
1415		1847
1416	=item $string = $program->source	1848	=item $string = $program->source
1417		1849
1418	Calls C<clGetProgramInfo> with C<CL_PROGRAM_SOURCE> and returns the result.	1850	Calls C<clGetProgramInfo> with C<OpenCL::PROGRAM_SOURCE> and returns the result.
1419		1851
1420	=item @ints = $program->binary_sizes	1852	=item @ints = $program->binary_sizes
1421		1853
1422	Calls C<clGetProgramInfo> with C<CL_PROGRAM_BINARY_SIZES> and returns the result.	1854	Calls C<clGetProgramInfo> with C<OpenCL::PROGRAM_BINARY_SIZES> and returns the result.
1423		1855
1424	=for gengetinfo end program	1856	=for gengetinfo end program
1425		1857
1426	=item @blobs = $program->binaries	1858	=item @blobs = $program->binaries
1427		1859
…		…
1448		1880
1449	=for gengetinfo begin kernel	1881	=for gengetinfo begin kernel
1450		1882
1451	=item $string = $kernel->function_name	1883	=item $string = $kernel->function_name
1452		1884
1453	Calls C<clGetKernelInfo> with C<CL_KERNEL_FUNCTION_NAME> and returns the result.	1885	Calls C<clGetKernelInfo> with C<OpenCL::KERNEL_FUNCTION_NAME> and returns the result.
1454		1886
1455	=item $uint = $kernel->num_args	1887	=item $uint = $kernel->num_args
1456		1888
1457	Calls C<clGetKernelInfo> with C<CL_KERNEL_NUM_ARGS> and returns the result.	1889	Calls C<clGetKernelInfo> with C<OpenCL::KERNEL_NUM_ARGS> and returns the result.
1458		1890
1459	=item $uint = $kernel->reference_count	1891	=item $uint = $kernel->reference_count
1460		1892
1461	Calls C<clGetKernelInfo> with C<CL_KERNEL_REFERENCE_COUNT> and returns the result.	1893	Calls C<clGetKernelInfo> with C<OpenCL::KERNEL_REFERENCE_COUNT> and returns the result.
1462		1894
1463	=item $ctx = $kernel->context	1895	=item $ctx = $kernel->context
1464		1896
1465	Calls C<clGetKernelInfo> with C<CL_KERNEL_CONTEXT> and returns the result.	1897	Calls C<clGetKernelInfo> with C<OpenCL::KERNEL_CONTEXT> and returns the result.
1466		1898
1467	=item $program = $kernel->program	1899	=item $program = $kernel->program
1468		1900
1469	Calls C<clGetKernelInfo> with C<CL_KERNEL_PROGRAM> and returns the result.	1901	Calls C<clGetKernelInfo> with C<OpenCL::KERNEL_PROGRAM> and returns the result.
1470		1902
1471	=for gengetinfo end kernel	1903	=for gengetinfo end kernel
1472		1904
1473	=item $packed_value = $kernel->work_group_info ($device, $name)	1905	=item $packed_value = $kernel->work_group_info ($device, $name)
1474		1906
1475	See C<< $platform->info >> for details.	1907	See C<< $platform->info >> for details.
1476		1908
1477	The reason this method is not called C<info> is that there already is an
1478	C<< ->info >> method.
1479
1480	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelWorkGroupInfo.html>	1909	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelWorkGroupInfo.html>
1481		1910
1482	=for gengetinfo begin kernel_work_group	1911	=for gengetinfo begin kernel_work_group
1483		1912
1484	=item $int = $kernel->work_group_size ($device)	1913	=item $int = $kernel->work_group_size ($device)
1485		1914
1486	Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_WORK_GROUP_SIZE> and returns the result.	1915	Calls C<clGetKernelWorkGroupInfo> with C<OpenCL::KERNEL_WORK_GROUP_SIZE> and returns the result.
1487		1916
1488	=item @ints = $kernel->compile_work_group_size ($device)	1917	=item @ints = $kernel->compile_work_group_size ($device)
1489		1918
1490	Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_COMPILE_WORK_GROUP_SIZE> and returns the result.	1919	Calls C<clGetKernelWorkGroupInfo> with C<OpenCL::KERNEL_COMPILE_WORK_GROUP_SIZE> and returns the result.
1491		1920
1492	=item $ulong = $kernel->local_mem_size ($device)	1921	=item $ulong = $kernel->local_mem_size ($device)
1493		1922
1494	Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_LOCAL_MEM_SIZE> and returns the result.	1923	Calls C<clGetKernelWorkGroupInfo> with C<OpenCL::KERNEL_LOCAL_MEM_SIZE> and returns the result.
1495		1924
1496	=item $int = $kernel->preferred_work_group_size_multiple ($device)	1925	=item $int = $kernel->preferred_work_group_size_multiple ($device)
1497		1926
1498	Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE> and returns the result.	1927	Calls C<clGetKernelWorkGroupInfo> with C<OpenCL::KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE> and returns the result.
1499		1928
1500	=item $ulong = $kernel->private_mem_size ($device)	1929	=item $ulong = $kernel->private_mem_size ($device)
1501		1930
1502	Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_PRIVATE_MEM_SIZE> and returns the result.	1931	Calls C<clGetKernelWorkGroupInfo> with C<OpenCL::KERNEL_PRIVATE_MEM_SIZE> and returns the result.
1503		1932
1504	=for gengetinfo end kernel_work_group	1933	=for gengetinfo end kernel_work_group
1505		1934
		1935	=item $packed_value = $kernel->arg_info ($idx, $name)
		1936
		1937	See C<< $platform->info >> for details.
		1938
		1939	L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clGetKernelArgInfo.html>
		1940
		1941	=for gengetinfo begin kernel_arg
		1942
		1943	=item $kernel_arg_address_qualifier = $kernel->arg_address_qualifier ($idx)
		1944
		1945	Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_ADDRESS_QUALIFIER> and returns the result.
		1946
		1947	=item $kernel_arg_access_qualifier = $kernel->arg_access_qualifier ($idx)
		1948
		1949	Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_ACCESS_QUALIFIER> and returns the result.
		1950
		1951	=item $string = $kernel->arg_type_name ($idx)
		1952
		1953	Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_TYPE_NAME> and returns the result.
		1954
		1955	=item $kernel_arg_type_qualifier = $kernel->arg_type_qualifier ($idx)
		1956
		1957	Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_TYPE_QUALIFIER> and returns the result.
		1958
		1959	=item $string = $kernel->arg_name ($idx)
		1960
		1961	Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_NAME> and returns the result.
		1962
		1963	=for gengetinfo end kernel_arg
		1964
		1965	=item $kernel->setf ($format, ...)
		1966
		1967	Sets the arguments of a kernel. Since OpenCL 1.1 doesn't have a generic
		1968	way to set arguments (and with OpenCL 1.2 it might be rather slow), you
		1969	need to specify a format argument, much as with C<printf>, to tell OpenCL
		1970	what type of argument it is.
		1971
		1972	The format arguments are single letters:
		1973
		1974	c char
		1975	C unsigned char
		1976	s short
		1977	S unsigned short
		1978	i int
		1979	I unsigned int
		1980	l long
		1981	L unsigned long
		1982
		1983	h half float (0..65535)
		1984	f float
		1985	d double
		1986
		1987	z local (octet size)
		1988
		1989	m memory object (buffer or image)
		1990	a sampler
		1991	e event
		1992
		1993	Space characters in the format string are ignored.
		1994
		1995	Example: set the arguments for a kernel that expects an int, two floats, a buffer and an image.
		1996
		1997	$kernel->setf ("i ff mm", 5, 0.5, 3, $buffer, $image);
		1998
1506	=item $kernel->set_TYPE ($index, $value)	1999	=item $kernel->set_TYPE ($index, $value)
1507		2000
		2001	=item $kernel->set_char ($index, $value)
		2002
		2003	=item $kernel->set_uchar ($index, $value)
		2004
		2005	=item $kernel->set_short ($index, $value)
		2006
		2007	=item $kernel->set_ushort ($index, $value)
		2008
		2009	=item $kernel->set_int ($index, $value)
		2010
		2011	=item $kernel->set_uint ($index, $value)
		2012
		2013	=item $kernel->set_long ($index, $value)
		2014
		2015	=item $kernel->set_ulong ($index, $value)
		2016
		2017	=item $kernel->set_half ($index, $value)
		2018
		2019	=item $kernel->set_float ($index, $value)
		2020
		2021	=item $kernel->set_double ($index, $value)
		2022
		2023	=item $kernel->set_memory ($index, $value)
		2024
		2025	=item $kernel->set_buffer ($index, $value)
		2026
		2027	=item $kernel->set_image ($index, $value)
		2028
		2029	=item $kernel->set_sampler ($index, $value)
		2030
		2031	=item $kernel->set_local ($index, $value)
		2032
		2033	=item $kernel->set_event ($index, $value)
		2034
1508	This is a family of methods to set the kernel argument with the number C<$index> to the give C<$value>.	2035	This is a family of methods to set the kernel argument with the number
1509		2036	C<$index> to the give C<$value>.
1510	TYPE is one of C<char>, C<uchar>, C<short>, C<ushort>, C<int>, C<uint>,
1511	C<long>, C<ulong>, C<half>, C<float>, C<double>, C<memory>, C<buffer>,
1512	C<image2d>, C<image3d>, C<sampler>, C<local> or C<event>.
1513		2037
1514	Chars and integers (including the half type) are specified as integers,	2038	Chars and integers (including the half type) are specified as integers,
1515	float and double as floating point values, memory/buffer/image2d/image3d	2039	float and double as floating point values, memory/buffer/image must be
1516	must be an object of that type or C<undef>, local-memory arguments are	2040	an object of that type or C<undef>, local-memory arguments are set by
1517	set by specifying the size, and sampler and event must be objects of that	2041	specifying the size, and sampler and event must be objects of that type.
1518	type.	2042
		2043	Note that C<set_memory> works for all memory objects (all types of buffers
		2044	and images) - the main purpose of the more specific C<set_TYPE> functions
		2045	is type checking.
1519		2046
1520	Setting an argument for a kernel does NOT keep a reference to the object -	2047	Setting an argument for a kernel does NOT keep a reference to the object -
1521	for example, if you set an argument to some image object, free the image,	2048	for example, if you set an argument to some image object, free the image,
1522	and call the kernel, you will run into undefined behaviour.	2049	and call the kernel, you will run into undefined behaviour.
1523		2050
…		…
1536		2063
1537	Waits for the event to complete.	2064	Waits for the event to complete.
1538		2065
1539	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html>	2066	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clWaitForEvents.html>
1540		2067
		2068	=item $ev->cb ($exec_callback_type, $callback->($event, $event_command_exec_status))
		2069
		2070	Adds a callback to the callback stack for the given event type. There is
		2071	no way to remove a callback again.
		2072
		2073	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetEventCallback.html>
		2074
1541	=item $packed_value = $ev->info ($name)	2075	=item $packed_value = $ev->info ($name)
1542		2076
1543	See C<< $platform->info >> for details.	2077	See C<< $platform->info >> for details.
1544		2078
1545	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetEventInfo.html>	2079	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetEventInfo.html>
1546		2080
1547	=for gengetinfo begin event	2081	=for gengetinfo begin event
1548		2082
1549	=item $queue = $event->command_queue	2083	=item $queue = $event->command_queue
1550		2084
1551	Calls C<clGetEventInfo> with C<CL_EVENT_COMMAND_QUEUE> and returns the result.	2085	Calls C<clGetEventInfo> with C<OpenCL::EVENT_COMMAND_QUEUE> and returns the result.
1552		2086
1553	=item $command_type = $event->command_type	2087	=item $command_type = $event->command_type
1554		2088
1555	Calls C<clGetEventInfo> with C<CL_EVENT_COMMAND_TYPE> and returns the result.	2089	Calls C<clGetEventInfo> with C<OpenCL::EVENT_COMMAND_TYPE> and returns the result.
1556		2090
1557	=item $uint = $event->reference_count	2091	=item $uint = $event->reference_count
1558		2092
1559	Calls C<clGetEventInfo> with C<CL_EVENT_REFERENCE_COUNT> and returns the result.	2093	Calls C<clGetEventInfo> with C<OpenCL::EVENT_REFERENCE_COUNT> and returns the result.
1560		2094
1561	=item $uint = $event->command_execution_status	2095	=item $uint = $event->command_execution_status
1562		2096
1563	Calls C<clGetEventInfo> with C<CL_EVENT_COMMAND_EXECUTION_STATUS> and returns the result.	2097	Calls C<clGetEventInfo> with C<OpenCL::EVENT_COMMAND_EXECUTION_STATUS> and returns the result.
1564		2098
1565	=item $ctx = $event->context	2099	=item $ctx = $event->context
1566		2100
1567	Calls C<clGetEventInfo> with C<CL_EVENT_CONTEXT> and returns the result.	2101	Calls C<clGetEventInfo> with C<OpenCL::EVENT_CONTEXT> and returns the result.
1568		2102
1569	=for gengetinfo end event	2103	=for gengetinfo end event
1570		2104
1571	=item $packed_value = $ev->profiling_info ($name)	2105	=item $packed_value = $ev->profiling_info ($name)
1572		2106
…		…
1579		2113
1580	=for gengetinfo begin profiling	2114	=for gengetinfo begin profiling
1581		2115
1582	=item $ulong = $event->profiling_command_queued	2116	=item $ulong = $event->profiling_command_queued
1583		2117
1584	Calls C<clGetEventProfilingInfo> with C<CL_PROFILING_COMMAND_QUEUED> and returns the result.	2118	Calls C<clGetEventProfilingInfo> with C<OpenCL::PROFILING_COMMAND_QUEUED> and returns the result.
1585		2119
1586	=item $ulong = $event->profiling_command_submit	2120	=item $ulong = $event->profiling_command_submit
1587		2121
1588	Calls C<clGetEventProfilingInfo> with C<CL_PROFILING_COMMAND_SUBMIT> and returns the result.	2122	Calls C<clGetEventProfilingInfo> with C<OpenCL::PROFILING_COMMAND_SUBMIT> and returns the result.
1589		2123
1590	=item $ulong = $event->profiling_command_start	2124	=item $ulong = $event->profiling_command_start
1591		2125
1592	Calls C<clGetEventProfilingInfo> with C<CL_PROFILING_COMMAND_START> and returns the result.	2126	Calls C<clGetEventProfilingInfo> with C<OpenCL::PROFILING_COMMAND_START> and returns the result.
1593		2127
1594	=item $ulong = $event->profiling_command_end	2128	=item $ulong = $event->profiling_command_end
1595		2129
1596	Calls C<clGetEventProfilingInfo> with C<CL_PROFILING_COMMAND_END> and returns the result.	2130	Calls C<clGetEventProfilingInfo> with C<OpenCL::PROFILING_COMMAND_END> and returns the result.
1597		2131
1598	=for gengetinfo end profiling	2132	=for gengetinfo end profiling
1599		2133
1600	=back	2134	=back
1601		2135
…		…
1605		2139
1606	=over 4	2140	=over 4
1607		2141
1608	=item $ev->set_status ($execution_status)	2142	=item $ev->set_status ($execution_status)
1609		2143
		2144	Sets the execution status of the user event. Can only be called once,
		2145	either with OpenCL::COMPLETE or a negative number as status.
		2146
		2147	execution_status: OpenCL::COMPLETE or a negative integer.
		2148
1610	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetUserEventStatus.html>	2149	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetUserEventStatus.html>
1611		2150
1612	=back	2151	=back
		2152
		2153	=head2 THE OpenCL::Mapped CLASS
		2154
		2155	This class represents objects mapped into host memory. They are
		2156	represented by a blessed string scalar. The string data is the mapped
		2157	memory area, that is, if you read or write it, then the mapped object is
		2158	accessed directly.
		2159
		2160	You must only ever use operations that modify the string in-place - for
		2161	example, a C<substr> that doesn't change the length, or maybe a regex that
		2162	doesn't change the length. Any other operation might cause the data to be
		2163	copied.
		2164
		2165	When the object is destroyed it will enqueue an implicit unmap operation
		2166	on the queue that was used to create it.
		2167
		2168	Keep in mind that you I<need> to unmap (or destroy) mapped objects before
		2169	OpenCL sees the changes, even if some implementations don't need this
		2170	sometimes.
		2171
		2172	Example, replace the first two floats in the mapped buffer by 1 and 2.
		2173
		2174	my $mapped = $queue->map_buffer ($buf, ...
		2175	$mapped->event->wait; # make sure it's there
		2176
		2177	# now replace first 8 bytes by new data, which is exactly 8 bytes long
		2178	# we blindly assume device endianness to equal host endianness
		2179	# (and of course, we assume iee 754 single precision floats :)
		2180	substr $$mapped, 0, 8, pack "f*", 1, 2;
		2181
		2182	=over 4
		2183
		2184	=item $ev = $mapped->unmap ($wait_events...)
		2185
		2186	Unmaps the mapped memory object, using the queue originally used to create
		2187	it, quite similarly to C<< $queue->unmap ($mapped, ...) >>.
		2188
		2189	=item $bool = $mapped->mapped
		2190
		2191	Returns whether the object is still mapped - true before an C<unmap> is
		2192	enqueued, false afterwards.
		2193
		2194	=item $ev = $mapped->event
		2195
		2196	Return the event object associated with the mapped object. Initially, this
		2197	will be the event object created when mapping the object, and after an
		2198	unmap, this will be the event object that the unmap operation created.
		2199
		2200	=item $mapped->wait
		2201
		2202	Same as C<< $mapped->event->wait >> - makes sure no operations on this
		2203	mapped object are outstanding.
		2204
		2205	=item $bytes = $mapped->size
		2206
		2207	Returns the size of the mapped area, in bytes. Same as C<length $$mapped>.
		2208
		2209	=item $ptr = $mapped->ptr
		2210
		2211	Returns the raw memory address of the mapped area.
		2212
		2213	=item $mapped->set ($offset, $data)
		2214
		2215	Replaces the data at the given C<$offset> in the memory area by the new
		2216	C<$data>. This method is safer than direct manipulation of C<$mapped>
		2217	because it does bounds-checking, but also slower.
		2218
		2219	=item $data = $mapped->get ($offset, $length)
		2220
		2221	Returns (without copying) a scalar representing the data at the given
		2222	C<$offset> and C<$length> in the mapped memory area. This is the same as
		2223	the following substr, except much slower;
		2224
		2225	$data = substr $$mapped, $offset, $length
		2226
		2227	=cut
		2228
		2229	sub OpenCL::Mapped::get {
		2230	substr ${$_[0]}, $_[1], $_[2]
		2231	}
		2232
		2233	=back
		2234
		2235	=head2 THE OpenCL::MappedBuffer CLASS
		2236
		2237	This is a subclass of OpenCL::Mapped, representing mapped buffers.
		2238
		2239	=head2 THE OpenCL::MappedImage CLASS
		2240
		2241	This is a subclass of OpenCL::Mapped, representing mapped images.
		2242
		2243	=over 4
		2244
		2245	=item $bytes = $mapped->row_pitch
		2246
		2247	=item $bytes = $mapped->slice_pitch
		2248
		2249	Return the row or slice pitch of the image that has been mapped.
		2250
		2251	=back
		2252
1613		2253
1614	=cut	2254	=cut
1615		2255
1616	1;	2256	1;
1617		2257

Diff Legend

–	Removed lines
+	Added lines
<	Changed lines
>	Changed lines