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

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.6 by root, Wed Nov 16 00:36:40 2011 UTC vs.
Revision 1.11 by root, Thu Nov 17 02:54:14 2011 UTC

…		…
6		6
7	use OpenCL;	7	use OpenCL;
8		8
9	=head1 DESCRIPTION	9	=head1 DESCRIPTION
10		10
11	This is an early release which might be useful, but hasn't seen any testing.	11	This is an early release which might be useful, but hasn't seen much testing.
12		12
		13	=head2 OpenCL FROM 10000 FEET HEIGHT
		14
		15	Here is a high level overview of OpenCL:
		16
		17	First you need to find one or more OpenCL::Platforms (kind of like
		18	vendors) - usually there is only one.
		19
		20	Each platform gives you access to a number of OpenCL::Device objects, e.g.
		21	your graphics card.
		22
		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
		25	most other objects:
		26
		27	OpenCL::Program objects, which store source code and, after building for a
		28	specific device ("compiling and linking"), also binary programs. For each
		29	kernel function in a program you can then create an OpenCL::Kernel object
		30	which represents basically a function call with argument values.
		31
		32	OpenCL::Memory objects of various flavours: OpenCL::Buffers objects (flat
		33	memory areas, think array) and OpenCL::Image objects (think 2d or 3d
		34	array) for bulk data and input and output for kernels.
		35
		36	OpenCL::Sampler objects, which are kind of like texture filter modes in
		37	OpenGL.
		38
		39	OpenCL::Queue objects - command queues, which allow you to submit memory
		40	reads, writes and copies, as well as kernel calls to your devices. They
		41	also offer a variety of methods to synchronise request execution, for
		42	example with barriers or OpenCL::Event objects.
		43
		44	OpenCL::Event objects are used to signal when something is complete.
		45
13	=head1 HELPFUL RESOURCES	46	=head2 HELPFUL RESOURCES
14		47
15	The OpenCL spec used to develop this module (1.2 spec was available, but	48	The OpenCL spec used to develop this module (1.2 spec was available, but
16	no implementation was available to me :).	49	no implementation was available to me :).
17		50
18	http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf	51	http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf
19		52
20	OpenCL manpages:	53	OpenCL manpages:
21		54
22	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/
23		56
		57	=head1 BASIC WORKFLOW
		58
		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):
		61
		62	Find some platform (e.g. the first one) and some device(s) (e.g. the first
		63	device of the platform), and create a context from those.
		64
		65	Create program objects from your OpenCL source code, then build (compile)
		66	the programs for each device you want to run them on.
		67
		68	Create kernel objects for all kernels you want to use (surprisingly, these
		69	are not device-specific).
		70
		71	Then, to execute stuff, you repeat these steps, possibly resuing or
		72	sharing some buffers:
		73
		74	Create some input and output buffers from your context. Set these as
		75	arguments to your kernel.
		76
		77	Enqueue buffer writes to initialise your input buffers (when not
		78	initialised at creation time).
		79
		80	Enqueue the kernel execution.
		81
		82	Enqueue buffer reads for your output buffer to read results.
		83
24	=head1 EXAMPLES	84	=head1 EXAMPLES
25		85
26	=head2 Enumerate all devices and get contexts for them.	86	=head2 Enumerate all devices and get contexts for them.
27		87
		88	Best run this once to get a feel for the platforms and devices in your
		89	system.
		90
28	for my $platform (OpenCL::platforms) {	91	for my $platform (OpenCL::platforms) {
29	warn $platform->info (OpenCL::PLATFORM_NAME);	92	printf "platform: %s\n", $platform->info (OpenCL::PLATFORM_NAME);
30	warn $platform->info (OpenCL::PLATFORM_EXTENSIONS);	93	printf "extensions: %s\n", $platform->info (OpenCL::PLATFORM_EXTENSIONS);
31	for my $device ($platform->devices) {	94	for my $device ($platform->devices) {
32	warn $device->info (OpenCL::DEVICE_NAME);	95	printf "+ device: %s\n", $device->info (OpenCL::DEVICE_NAME);
33	my $ctx = $device->context_simple;	96	my $ctx = $device->context;
34	# do stuff	97	# do stuff
35	}	98	}
36	}	99	}
37		100
38	=head2 Get a useful context and a command queue.	101	=head2 Get a useful context and a command queue.
39		102
40	my $dev = ((OpenCL::platforms)[0]->devices)[0];	103	This is a useful boilerplate for any OpenCL program that only wants to use
41	my $ctx = $dev->context_simple;	104	one device,
42	my $queue = $ctx->command_queue_simple ($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
43		110
44	=head2 Print all supported image formats of a context.	111	=head2 Print all supported image formats of a context.
45		112
		113	Best run this once for your context, to see whats available and how to
		114	gather information.
		115
46	for my $type (OpenCL::MEM_OBJECT_IMAGE2D, OpenCL::MEM_OBJECT_IMAGE3D) {	116	for my $type (OpenCL::MEM_OBJECT_IMAGE2D, OpenCL::MEM_OBJECT_IMAGE3D) {
47	say "supported image formats for ", OpenCL::enum2str $type;	117	print "supported image formats for ", OpenCL::enum2str $type, "\n";
48		118
49	for my $f ($ctx->supported_image_formats (0, $type)) {	119	for my $f ($ctx->supported_image_formats (0, $type)) {
50	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];
51	}	121	}
52	}	122	}
…		…
55	then asynchronously.	125	then asynchronously.
56		126
57	my $buf = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, "helmut");	127	my $buf = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, "helmut");
58		128
59	$queue->enqueue_read_buffer ($buf, 1, 1, 3, my $data);	129	$queue->enqueue_read_buffer ($buf, 1, 1, 3, my $data);
60	warn $data;	130	print "$data\n";
61		131
62	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);
63	$ev->wait;	133	$ev->wait;
64	warn $data;	134	print "$data\n"; # prints "elm"
65		135
66	=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
67	functions.	137	functions.
68		138
69	my $src = '	139	my $src = '
…		…
75	}	145	}
76	';	146	';
77		147
78	my $prog = $ctx->program_with_source ($src);	148	my $prog = $ctx->program_with_source ($src);
79		149
		150	# build croaks on compile errors, so catch it and print the compile errors
80	eval { $prog->build ($dev); 1 }	151	eval { $prog->build ($dev); 1 }
81	or die $prog->build_info ($dev, OpenCL::PROGRAM_BUILD_LOG);	152	or die $prog->build_info ($dev, OpenCL::PROGRAM_BUILD_LOG);
82		153
83	my $kernel = $prog->kernel ("squareit");	154	my $kernel = $prog->kernel ("squareit");
84		155
85	=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.
86		158
87	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);
88	my $output = $ctx->buffer (0, OpenCL::SIZEOF_FLOAT * 5);	160	my $output = $ctx->buffer (0, OpenCL::SIZEOF_FLOAT * 5);
89		161
90	# set buffer	162	# set buffer
…		…
96		168
97	# enqueue a synchronous read	169	# enqueue a synchronous read
98	$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);
99		171
100	# print the results:	172	# print the results:
101	say join ", ", unpack "f*", $data;	173	printf "%s\n", join ", ", unpack "f*", $data;
102		174
103	=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,
104	showing off barriers.	176	showing off barriers.
105		177
106	# execute it for all 4 numbers	178	# execute it for all 4 numbers
…		…
148		220
149	=item * OpenCL often specifies fixed vector function arguments as short	221	=item * OpenCL often specifies fixed vector function arguments as short
150	arrays (C<size_t origin[3]>), while this module explicitly expects the	222	arrays (C<size_t origin[3]>), while this module explicitly expects the
151	components as separate arguments-	223	components as separate arguments-
152		224
153	=item * Where possible, the row_pitch value is calculated from the perl	225	=item * Where possible, one of the pitch values is calculated from the
154	scalar length and need not be specified.	226	perl scalar length and need not be specified.
155		227
156	=item * When enqueuing commands, the wait list is specified by adding	228	=item * When enqueuing commands, the wait list is specified by adding
157	extra arguments to the function - everywhere a C<$wait_events...> argument	229	extra arguments to the function - anywhere a C<$wait_events...> argument
158	is documented this can be any number of event objects.	230	is documented this can be any number of event objects.
159		231
160	=item * When enqueuing commands, if the enqueue method is called in void	232	=item * When enqueuing commands, if the enqueue method is called in void
161	context, no event is created. In all other contexts an event is returned	233	context, no event is created. In all other contexts an event is returned
162	by the method.	234	by the method.
…		…
165	other status is returned the function will throw an exception, so you	237	other status is returned the function will throw an exception, so you
166	don't normally have to to any error checking.	238	don't normally have to to any error checking.
167		239
168	=back	240	=back
169		241
		242	=head2 PERL AND OPENCL TYPES
		243
		244	This handy(?) table lists OpenCL types and their perl, PDL and pack/unpack
		245	format equivalents:
		246
		247	OpenCL perl PDL pack/unpack
		248	char IV - c
		249	uchar IV byte C
		250	short IV short s
		251	ushort IV ushort S
		252	int IV long? l
		253	uint IV - L
		254	long IV longlong q
		255	ulong IV - Q
		256	float NV float f
		257	half IV ushort S
		258	double NV double d
		259
170	=head2 THE OpenCL PACKAGE	260	=head2 THE OpenCL PACKAGE
171		261
172	=over 4	262	=over 4
173		263
174	=item $int = OpenCL::errno	264	=item $int = OpenCL::errno
175		265
176	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.
177		268
178	=item $str = OpenCL::err2str $errval	269	=item $str = OpenCL::err2str $errval
179		270
180	Comverts an error value into a human readable string.	271	Comverts an error value into a human readable string.
181		272
182	=item $str = OpenCL::err2str $enum	273	=item $str = OpenCL::enum2str $enum
183		274
184	Converts most enum values (inof parameter names, image format constants,	275	Converts most enum values (inof parameter names, image format constants,
185	object types, addressing and filter modes, command types etc.) into a	276	object types, addressing and filter modes, command types etc.) into a
186	human readbale string. When confronted with some random integer it can be	277	human readbale string. When confronted with some random integer it can be
187	very helpful to pass it through this function to maybe get some readable	278	very helpful to pass it through this function to maybe get some readable
…		…
191		282
192	Returns all available OpenCL::Platform objects.	283	Returns all available OpenCL::Platform objects.
193		284
194	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>
195		286
196	=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
197		288
198	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.
199		290
200	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>
201		292
…		…
221		312
222	=item @devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL)	313	=item @devices = $platform->devices ($type = OpenCL::DEVICE_TYPE_ALL)
223		314
224	Returns a list of matching OpenCL::Device objects.	315	Returns a list of matching OpenCL::Device objects.
225		316
226	=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)
227		318
228	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.
229		320
230	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>
231		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
232	=back	330	=back
233		331
234	=head2 THE OpenCL::Device CLASS	332	=head2 THE OpenCL::Device CLASS
235		333
236	=over 4	334	=over 4
…		…
239		337
240	See C<< $platform->info >> for details.	338	See C<< $platform->info >> for details.
241		339
242	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>
243		341
244	=item $ctx = $device->context_simple
245
246	Convenience function to create a new OpenCL::Context object.
247
248	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContext.html>
249
250	=back	342	=back
251		343
252	=head2 THE OpenCL::Context CLASS	344	=head2 THE OpenCL::Context CLASS
253		345
254	=over 4	346	=over 4
…		…
257		349
258	See C<< $platform->info >> for details.	350	See C<< $platform->info >> for details.
259		351
260	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html>	352	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html>
261		353
262	=item $queue = $ctx->command_queue_simple ($device)	354	=item $queue = $ctx->queue ($device, $properties)
263		355
264	Convenience function to create a new OpenCL::Queue object from the context and the given device.	356	Create a new OpenCL::Queue object from the context and the given device.
265		357
266	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateCommandQueue.html>	358	L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateCommandQueue.html>
267		359
268	=item $ev = $ctx->user_event	360	=item $ev = $ctx->user_event
269		361

Diff Legend

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

Comparing OpenCL/OpenCL.pm (file contents): Revision 1.6 by root, Wed Nov 16 00:36:40 2011 UTC vs. Revision 1.11 by root, Thu Nov 17 02:54:14 2011 UTC

Diff Legend

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.6 by root, Wed Nov 16 00:36:40 2011 UTC vs.
Revision 1.11 by root, Thu Nov 17 02:54:14 2011 UTC