[ViewVC] Diff of: cvs/OpenCL/OpenCL.pm

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.9 by root, Thu Nov 17 01:36:52 2011 UTC vs.
Revision 1.12 by root, Thu Nov 17 02:56:47 2011 UTC

…		…
18	vendors) - usually there is only one.	18	vendors) - usually there is only one.
19		19
20	Each platform gives you access to a number of OpenCL::Device objects, e.g.	20	Each platform gives you access to a number of OpenCL::Device objects, e.g.
21	your graphics card.	21	your graphics card.
22		22
23	From a platform and some devices, you create an OpenCL::Context, which is	23	From a platform and some device(s), you create an OpenCL::Context, which is
24	a very central object in OpenCL: Once you have a context you can create	24	a very central object in OpenCL: Once you have a context you can create
25	most other objects:	25	most other objects:
26		26
27	OpenCL::Program objects, which store source code and, after building	27	OpenCL::Program objects, which store source code and, after building for a
28	("compiling and linking"), also binary programs. For each kernel function	28	specific device ("compiling and linking"), also binary programs. For each
29	in a program you can then create an OpenCL::Kernel object which represents	29	kernel function in a program you can then create an OpenCL::Kernel object
30	basically a function call with argument values.	30	which represents basically a function call with argument values.
31		31
32	OpenCL::Memory objects of various flavours: OpenCL::Buffers objects (flat	32	OpenCL::Memory objects of various flavours: OpenCL::Buffers objects (flat
33	memory areas, think array) and OpenCL::Image objects (think 2d or 3d	33	memory areas, think array) and OpenCL::Image objects (think 2d or 3d
34	array) for bulk data and input and output for kernels.	34	array) for bulk data and input and output for kernels.
35		35
…		…
54		54
55	http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/	55	http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/
56		56
57	=head1 BASIC WORKFLOW	57	=head1 BASIC WORKFLOW
58		58
59	To get something done, you basically have to do this once:	59	To get something done, you basically have to do this once (refer to the
		60	examples below for actual code, this is just a high-level description):
60		61
61	Find some platform (e.g. the first one) and some device (e.g. the first	62	Find some platform (e.g. the first one) and some device(s) (e.g. the first
62	device you can find), and create a context from those.	63	device of the platform), and create a context from those.
63		64
64	Create a command queue from your context, and program objects from your	65	Create program objects from your OpenCL source code, then build (compile)
65	OpenCL source code, build the programs.	66	the programs for each device you want to run them on.
66		67
67	Create kernel objects for all kernels you want to use.	68	Create kernel objects for all kernels you want to use (surprisingly, these
		69	are not device-specific).
68		70
69	Then, to execute stuff, you repeat this:	71	Then, to execute stuff, you repeat these steps, possibly resuing or
		72	sharing some buffers:
70		73
71	Create some input and output buffers from your context. Initialise the	74	Create some input and output buffers from your context. Set these as
72	input buffers with data. Set these as arguments to your kernel.	75	arguments to your kernel.
		76
		77	Enqueue buffer writes to initialise your input buffers (when not
		78	initialised at creation time).
73		79
74	Enqueue the kernel execution.	80	Enqueue the kernel execution.
75		81
76	Enqueue buffer reads for your output buffer to read results.	82	Enqueue buffer reads for your output buffer to read results.
77		83
78	The next section shows how this can be done.
79
80	=head1 EXAMPLES	84	=head1 EXAMPLES
81		85
82	=head2 Enumerate all devices and get contexts for them.	86	=head2 Enumerate all devices and get contexts for them.
83		87
		88	Best run this once to get a feel for the platforms and devices in your
		89	system.
		90
84	for my $platform (OpenCL::platforms) {	91	for my $platform (OpenCL::platforms) {
85	warn $platform->info (OpenCL::PLATFORM_NAME);	92	printf "platform: %s\n", $platform->info (OpenCL::PLATFORM_NAME);
86	warn $platform->info (OpenCL::PLATFORM_EXTENSIONS);	93	printf "extensions: %s\n", $platform->info (OpenCL::PLATFORM_EXTENSIONS);
87	for my $device ($platform->devices) {	94	for my $device ($platform->devices) {
88	warn $device->info (OpenCL::DEVICE_NAME);	95	printf "+ device: %s\n", $device->info (OpenCL::DEVICE_NAME);
89	my $ctx = $device->context_simple;	96	my $ctx = $device->context;
90	# do stuff	97	# do stuff
91	}	98	}
92	}	99	}
93		100
94	=head2 Get a useful context and a command queue.	101	=head2 Get a useful context and a command queue.
95		102
96	my $dev = ((OpenCL::platforms)[0]->devices)[0];	103	This is a useful boilerplate for any OpenCL program that only wants to use
97	my $ctx = $dev->context_simple;	104	one device,
98	my $queue = $ctx->queue ($dev);	105
		106	my ($platform) = OpenCL::platforms; # find first platform
		107	my ($dev) = $platform->devices; # find first device of platform
		108	my $ctx = $platform->context (undef, [$dev]); # create context out of those
		109	my $queue = $ctx->queue ($dev); # create a command queue for the device
99		110
100	=head2 Print all supported image formats of a context.	111	=head2 Print all supported image formats of a context.
101		112
		113	Best run this once for your context, to see whats available and how to
		114	gather information.
		115
102	for my $type (OpenCL::MEM_OBJECT_IMAGE2D, OpenCL::MEM_OBJECT_IMAGE3D) {	116	for my $type (OpenCL::MEM_OBJECT_IMAGE2D, OpenCL::MEM_OBJECT_IMAGE3D) {
103	say "supported image formats for ", OpenCL::enum2str $type;	117	print "supported image formats for ", OpenCL::enum2str $type, "\n";
104		118
105	for my $f ($ctx->supported_image_formats (0, $type)) {	119	for my $f ($ctx->supported_image_formats (0, $type)) {
106	printf " %-10s %-20s\n", OpenCL::enum2str $f->[0], OpenCL::enum2str $f->[1];	120	printf " %-10s %-20s\n", OpenCL::enum2str $f->[0], OpenCL::enum2str $f->[1];
107	}	121	}
108	}	122	}
…		…
111	then asynchronously.	125	then asynchronously.
112		126
113	my $buf = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, "helmut");	127	my $buf = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, "helmut");
114		128
115	$queue->enqueue_read_buffer ($buf, 1, 1, 3, my $data);	129	$queue->enqueue_read_buffer ($buf, 1, 1, 3, my $data);
116	warn $data;	130	print "$data\n";
117		131
118	my $ev = $queue->enqueue_read_buffer ($buf, 0, 1, 3, my $data);	132	my $ev = $queue->enqueue_read_buffer ($buf, 0, 1, 3, my $data);
119	$ev->wait;	133	$ev->wait;
120	warn $data;	134	print "$data\n"; # prints "elm"
121		135
122	=head2 Create and build a program, then create a kernel out of one of its	136	=head2 Create and build a program, then create a kernel out of one of its
123	functions.	137	functions.
124		138
125	my $src = '	139	my $src = '
…		…
131	}	145	}
132	';	146	';
133		147
134	my $prog = $ctx->program_with_source ($src);	148	my $prog = $ctx->program_with_source ($src);
135		149
		150	# build croaks on compile errors, so catch it and print the compile errors
136	eval { $prog->build ($dev); 1 }	151	eval { $prog->build ($dev); 1 }
137	or die $prog->build_info ($dev, OpenCL::PROGRAM_BUILD_LOG);	152	or die $prog->build_info ($dev, OpenCL::PROGRAM_BUILD_LOG);
138		153
139	my $kernel = $prog->kernel ("squareit");	154	my $kernel = $prog->kernel ("squareit");
140		155
141	=head2 Create some input and output float buffers, then call squareit on them.	156	=head2 Create some input and output float buffers, then call the
		157	'squareit' kernel on them.
142		158
143	my $input = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, pack "f*", 1, 2, 3, 4.5);	159	my $input = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, pack "f*", 1, 2, 3, 4.5);
144	my $output = $ctx->buffer (0, OpenCL::SIZEOF_FLOAT * 5);	160	my $output = $ctx->buffer (0, OpenCL::SIZEOF_FLOAT * 5);
145		161
146	# set buffer	162	# set buffer
…		…
152		168
153	# enqueue a synchronous read	169	# enqueue a synchronous read
154	$queue->enqueue_read_buffer ($output, 1, 0, OpenCL::SIZEOF_FLOAT * 4, my $data);	170	$queue->enqueue_read_buffer ($output, 1, 0, OpenCL::SIZEOF_FLOAT * 4, my $data);
155		171
156	# print the results:	172	# print the results:
157	say join ", ", unpack "f*", $data;	173	printf "%s\n", join ", ", unpack "f*", $data;
158		174
159	=head2 The same enqueue operations as before, but assuming an out-of-order queue,	175	=head2 The same enqueue operations as before, but assuming an out-of-order queue,
160	showing off barriers.	176	showing off barriers.
161		177
162	# execute it for all 4 numbers	178	# execute it for all 4 numbers
…		…
245		261
246	=over 4	262	=over 4
247		263
248	=item $int = OpenCL::errno	264	=item $int = OpenCL::errno
249		265
250	The last error returned by a function - it's only changed on errors.	266	The last error returned by a function - it's only valid after an error occured
		267	and before calling another OpenCL function.
251		268
252	=item $str = OpenCL::err2str $errval	269	=item $str = OpenCL::err2str $errval
253		270
254	Comverts an error value into a human readable string.	271	Comverts an error value into a human readable string.
255		272
…		…
265		282
266	Returns all available OpenCL::Platform objects.	283	Returns all available OpenCL::Platform objects.
267		284
268	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformIDs.html>	285	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlatformIDs.html>
269		286
270	=item $ctx = OpenCL::context_from_type_simple $type = OpenCL::DEVICE_TYPE_DEFAULT	287	=item $ctx = OpenCL::context_from_type $properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $notify = undef
271		288
272	Tries to create a context from a default device and platform - never worked for me.	289	Tries to create a context from a default device and platform - never worked for me.
273		290
274	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>	291	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>
275		292
…		…
295		312
296	=item @devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL)	313	=item @devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL)
297		314
298	Returns a list of matching OpenCL::Device objects.	315	Returns a list of matching OpenCL::Device objects.
299		316
300	=item $ctx = $platform->context_from_type_simple ($type = OpenCL::DEVICE_TYPE_DEFAULT)	317	=item $ctx = $platform->context_from_type ($properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $notify = undef)
301		318
302	Tries to create a context. Never worked for me.	319	Tries to create a context. Never worked for me, and you need devices explitly anyway.
303		320
304	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>	321	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>
305		322
		323	=item $ctx = $device->context ($properties = undef, @$devices, $notify = undef)
		324
		325	Create a new OpenCL::Context object using the given device object(s)- a
		326	CL_CONTEXT_PLATFORM property is supplied automatically.
		327
		328	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html>
		329
306	=back	330	=back
307		331
308	=head2 THE OpenCL::Device CLASS	332	=head2 THE OpenCL::Device CLASS
309		333
310	=over 4	334	=over 4
…		…
312	=item $packed_value = $device->info ($name)	336	=item $packed_value = $device->info ($name)
313		337
314	See C<< $platform->info >> for details.	338	See C<< $platform->info >> for details.
315		339
316	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html>	340	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html>
317
318	=item $ctx = $device->context_simple
319
320	Convenience function to create a new OpenCL::Context object.
321
322	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html>
323		341
324	=back	342	=back
325		343
326	=head2 THE OpenCL::Context CLASS	344	=head2 THE OpenCL::Context CLASS
327		345
…		…
625	package OpenCL;	643	package OpenCL;
626		644
627	use common::sense;	645	use common::sense;
628		646
629	BEGIN {	647	BEGIN {
630	our $VERSION = '0.03';	648	our $VERSION = '0.14';
631		649
632	require XSLoader;	650	require XSLoader;
633	XSLoader::load (__PACKAGE__, $VERSION);	651	XSLoader::load (__PACKAGE__, $VERSION);
634		652
635	@OpenCL::Buffer::ISA =	653	@OpenCL::Buffer::ISA =

Diff Legend

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

Comparing OpenCL/OpenCL.pm (file contents): Revision 1.9 by root, Thu Nov 17 01:36:52 2011 UTC vs. Revision 1.12 by root, Thu Nov 17 02:56:47 2011 UTC

Diff Legend

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.9 by root, Thu Nov 17 01:36:52 2011 UTC vs.
Revision 1.12 by root, Thu Nov 17 02:56:47 2011 UTC