ViewVC Help

View File | Revision Log | Show Annotations | Download File

/cvs/OpenCL/OpenCL.pm

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

Diff Legend

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