--- OpenCL/OpenCL.pm 2012/04/24 13:30:49 1.50 +++ OpenCL/OpenCL.pm 2012/05/05 16:52:17 1.85 @@ -30,8 +30,8 @@ which represents basically a function call with argument values. OpenCL::Memory objects of various flavours: OpenCL::Buffer objects (flat -memory areas, think arrays or structs) and OpenCL::Image objects (think 2d -or 3d array) for bulk data and input and output for kernels. +memory areas, think arrays or structs) and OpenCL::Image objects (think 2D +or 3D array) for bulk data and input and output for kernels. OpenCL::Sampler objects, which are kind of like texture filter modes in OpenGL. @@ -45,19 +45,23 @@ =head2 HELPFUL RESOURCES -The OpenCL spec used to develop this module (1.2 spec was available, but -no implementation was available to me :). +The OpenCL specs used to develop this module - download these and keept +hema round, they are required reference material: http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf + http://www.khronos.org/registry/cl/specs/opencl-1.2.pdf + http://www.khronos.org/registry/cl/specs/opencl-1.2-extensions.pdf OpenCL manpages: http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/ + http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/ If you are into UML class diagrams, the following diagram might help - if -not, it will be mildly cobfusing: +not, it will be mildly confusing (also, the class hierarchy of this module +is much more fine-grained): - http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/classDiagram.html + http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/classDiagram.html Here's a tutorial from AMD (very AMD-centric, too), not sure how useful it is, but at least it's free of charge: @@ -140,10 +144,10 @@ my $buf = $ctx->buffer_sv (OpenCL::MEM_COPY_HOST_PTR, "helmut"); - $queue->enqueue_read_buffer ($buf, 1, 1, 3, my $data); + $queue->read_buffer ($buf, 1, 1, 3, my $data); print "$data\n"; - my $ev = $queue->enqueue_read_buffer ($buf, 0, 1, 3, my $data); + my $ev = $queue->read_buffer ($buf, 0, 1, 3, my $data); $ev->wait; print "$data\n"; # prints "elm" @@ -159,12 +163,7 @@ } '; - my $prog = $ctx->program_with_source ($src); - - # build croaks on compile errors, so catch it and print the compile errors - eval { $prog->build ($dev, "-cl-fast-relaxed-math"); 1 } - or die $prog->build_log; - + my $prog = $ctx->build_program ($src); my $kernel = $prog->kernel ("squareit"); =head2 Create some input and output float buffers, then call the @@ -178,10 +177,10 @@ $kernel->set_buffer (1, $output); # execute it for all 4 numbers - $queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef); + $queue->nd_range_kernel ($kernel, undef, [4], undef); # enqueue a synchronous read - $queue->enqueue_read_buffer ($output, 1, 0, OpenCL::SIZEOF_FLOAT * 4, my $data); + $queue->read_buffer ($output, 1, 0, OpenCL::SIZEOF_FLOAT * 4, my $data); # print the results: printf "%s\n", join ", ", unpack "f*", $data; @@ -190,13 +189,13 @@ showing off barriers. # execute it for all 4 numbers - $queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef); + $queue->nd_range_kernel ($kernel, undef, [4], undef); # enqueue a barrier to ensure in-order execution - $queue->enqueue_barrier; + $queue->barrier; # enqueue an async read - $queue->enqueue_read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data); + $queue->read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data); # wait for all requests to finish $queue->finish; @@ -205,27 +204,30 @@ showing off event objects and wait lists. # execute it for all 4 numbers - my $ev = $queue->enqueue_nd_range_kernel ($kernel, undef, [4], undef); + my $ev = $queue->nd_range_kernel ($kernel, undef, [4], undef); # enqueue an async read - $ev = $queue->enqueue_read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data, $ev); + $ev = $queue->read_buffer ($output, 0, 0, OpenCL::SIZEOF_FLOAT * 4, my $data, $ev); # wait for the last event to complete $ev->wait; =head2 Use the OpenGL module to share a texture between OpenCL and OpenGL and draw some julia -set tunnel effect. +set flight effect. -This is quite a long example to get you going. +This is quite a long example to get you going - you can also download it +from L. use OpenGL ":all"; use OpenCL; + my $S = $ARGV[0] || 256; # window/texture size, smaller is faster + # open a window and create a gl texture - OpenGL::glpOpenWindow width => 256, height => 256; + OpenGL::glpOpenWindow width => $S, height => $S; my $texid = glGenTextures_p 1; glBindTexture GL_TEXTURE_2D, $texid; - glTexImage2D_c GL_TEXTURE_2D, 0, GL_RGBA8, 256, 256, 0, GL_RGBA, GL_UNSIGNED_BYTE, 0; + glTexImage2D_c GL_TEXTURE_2D, 0, GL_RGBA8, $S, $S, 0, GL_RGBA, GL_UNSIGNED_BYTE, 0; # find and use the first opencl device that let's us get a shared opengl context my $platform; @@ -254,40 +256,38 @@ kernel void juliatunnel (write_only image2d_t img, float time) { - float2 p = (float2)(get_global_id (0), get_global_id (1)) / 256.f * 2.f - 1.f; + int2 xy = (int2)(get_global_id (0), get_global_id (1)); + float2 p = convert_float2 (xy) / $S.f * 2.f - 1.f; - float2 m = (float2)(1.f, p.y) / fabs (p.x); - m.x = fabs (fmod (m.x + time * 0.05f, 4.f)) - 2.f; + float2 m = (float2)(1.f, p.y) / fabs (p.x); // tunnel + m.x = fabs (fmod (m.x + time * 0.05f, 4.f) - 2.f); float2 z = m; - float2 c = (float2)(sin (time * 0.05005), cos (time * 0.06001)); + float2 c = (float2)(sin (time * 0.01133f), cos (time * 0.02521f)); - for (int i = 0; i < 25 && dot (z, z) < 4.f; ++i) + for (int i = 0; i < 25 && dot (z, z) < 4.f; ++i) // standard julia z = (float2)(z.x * z.x - z.y * z.y, 2.f * z.x * z.y) + c; - float3 colour = (float3)(z.x, z.y, z.x * z.y); - write_imagef (img, (int2)(get_global_id (0), get_global_id (1)), (float4)(colour * p.x * p.x, 1.)); + float3 colour = (float3)(z.x, z.y, atan2 (z.y, z.x)); + write_imagef (img, xy, (float4)(colour * p.x * p.x, 1.)); } EOF - my $prog = $ctx->program_with_source ($src); - eval { $prog->build ($dev); 1 } - or die $prog->build_log ($dev); + my $prog = $ctx->build_program ($src); my $kernel = $prog->kernel ("juliatunnel"); # program compiled, kernel ready, now draw and loop for (my $time; ; ++$time) { # acquire objects from opengl - $queue->enqueue_acquire_gl_objects ([$tex]); + $queue->acquire_gl_objects ([$tex]); # configure and run our kernel - $kernel->set_image2d (0, $tex); - $kernel->set_float (1, $time); - $queue->enqueue_nd_range_kernel ($kernel, undef, [256, 256], undef); + $kernel->setf ("mf", $tex, $time*2); # mf = memory object, float + $queue->nd_range_kernel ($kernel, undef, [$S, $S], undef); # release objects to opengl again - $queue->enqueue_release_gl_objects ([$tex]); + $queue->release_gl_objects ([$tex]); # wait $queue->finish; @@ -308,6 +308,50 @@ select undef, undef, undef, 1/60; } +=head2 How to modify the previous example to not rely on GL sharing. + +For those poor souls with only a sucky CPU OpenCL implementation, you +currently have to read the image into some perl scalar, and then modify a +texture or use glDrawPixels or so). + +First, when you don't need gl sharing, you can create the context much simpler: + + $ctx = $platform->context (undef, [$dev]) + +To use a texture, you would modify the above example by creating an +OpenCL::Image manually instead of deriving it from a texture: + + my $tex = $ctx->image2d (OpenCL::MEM_WRITE_ONLY, OpenCL::RGBA, OpenCL::UNORM_INT8, $S, $S); + +And in the draw loop, intead of acquire_gl_objects/release_gl_objects, you +would read the image2d after the kernel has written it: + + $queue->read_image ($tex, 0, 0, 0, 0, $S, $S, 1, 0, 0, my $data); + +And then you would upload the pixel data to the texture (or use glDrawPixels): + + glTexSubImage2D_s GL_TEXTURE_2D, 0, 0, 0, $S, $S, GL_RGBA, GL_UNSIGNED_BYTE, $data; + +The fully modified example can be found at +L. + +=head2 Julia sets look soooo 80ies. + +Then colour them differently, e.g. using orbit traps! Replace the loop and +colour calculation from the previous examples by this: + + float2 dm = (float2)(1.f, 1.f); + + for (int i = 0; i < 25; ++i) + { + z = (float2)(z.x * z.x - z.y * z.y, 2.f * z.x * z.y) + c; + dm = fmin (dm, (float2)(fabs (dot (z, z) - 1.f), fabs (z.x - 1.f))); + } + + float3 colour = (float3)(dm.x * dm.y, dm.x * dm.y, dm.x); + +Also try C<-10.f> instead of C<-1.f>. + =head1 DOCUMENTATION =head2 BASIC CONVENTIONS @@ -346,12 +390,53 @@ context, no event is created. In all other contexts an event is returned by the method. -=item * This module expects all functions to return C. If any +=item * This module expects all functions to return C. If any other status is returned the function will throw an exception, so you don't normally have to to any error checking. =back +=head2 CONSTANTS + +All C constants that this module supports are always available +in the C namespace as C (i.e. without the C +prefix). Constants which are not defined in the header files used during +compilation, or otherwise are not available, will have the value C<-1>. + +The latest version of this module knows and exports the constants +listed in L. + +=head2 OPENCL 1.1 VS. OPENCL 1.2 + +This module supports both OpenCL version 1.1 and 1.2, although the OpenCL +1.2 interface hasn't been tested much for lack of availability of an +actual implementation. + +Every function or method in this manual page that interfaces to a +particular OpenCL function has a link to the its C manual page. + +If the link contains a F<1.1>, then this function is an OpenCL 1.1 +function. Most but not all also exist in OpenCL 1.2, and this module +tries to emulate the missing ones for you, when told to do so at +compiletime. You can check whether a function was removed in OpenCL 1.2 by +replacing the F<1.1> component in the URL by F<1.2>. + +If the link contains a F<1.2>, then this is a OpenCL 1.2-only +function. Even if the module was compiled with OpenCL 1.2 header files +and has an 1.2 OpenCL library, calling such a function on a platform that +doesn't implement 1.2 causes undefined behaviour, usually a crash (But +this is not guaranteed). + +You can find out whether this module was compiled to prefer 1.1 +functionality by ooking at C - if it is true, then +1.1 functions generally are implemented using 1.1 OpenCL functions. If it +is false, then 1.1 functions missing from 1.2 are emulated by calling 1.2 +fucntions. + +This is a somewhat sorry state of affairs, but the Khronos group choose to +make every release of OpenCL source and binary incompatible with previous +releases. + =head2 PERL AND OPENCL TYPES This handy(?) table lists OpenCL types and their perl, PDL and pack/unpack @@ -385,6 +470,168 @@ have been created and be made current, and C must be available and capable of finding the function via C. +=head2 EVENT SYSTEM + +OpenCL can generate a number of (potentially) asynchronous events, for +example, after compiling a program, to signal a context-related error or, +perhaps most important, to signal completion of queued jobs (by setting +callbacks on OpenCL::Event objects). + +The OpenCL module converts all these callbacks into events - you can +still register callbacks, but they are not executed when your OpenCL +implementation calls the actual callback, but only later. Therefore, none +of the limitations of OpenCL callbacks apply to the perl implementation: +it is perfectly safe to make blocking operations from event callbacks, and +enqueued operations don't need to be flushed. + +To facilitate this, this module maintains an event queue - each +time an asynchronous event happens, it is queued, and perl will be +interrupted. This is implemented via the L module. In +addition, this module has L support, so it can seamlessly +integrate itself into many event loops. + +Since L is a bit hard to understand, here are some case examples: + +=head3 Don't use callbacks. + +When your program never uses any callbacks, then there will never be any +notifications you need to take care of, and therefore no need to worry +about all this. + +You can achieve a great deal by explicitly waiting for events, or using +barriers and flush calls. In many programs, there is no need at all to +tinker with asynchronous events. + +=head3 Use AnyEvent + +This module automatically registers a watcher that invokes all outstanding +event callbacks when AnyEvent is initialised (and block asynchronous +interruptions). Using this mode of operations is the safest and most +recommended one. + +To use this, simply use AnyEvent and this module normally, make sure you +have an event loop running: + + use Gtk2 -init; + use AnyEvent; + + # initialise AnyEvent, by creating a watcher, or: + AnyEvent::detect; + + my $e = $queue->marker; + $e->cb (sub { + warn "opencl is finished\n"; + }) + + main Gtk2; + +Note that this module will not initialise AnyEvent for you. Before +AnyEvent is initialised, the module will asynchronously interrupt perl +instead. To avoid any surprises, it's best to explicitly initialise +AnyEvent. + +You can temporarily enable asynchronous interruptions (see next paragraph) +by calling C<$OpenCL::INTERRUPT->unblock> and disable them again by +calling C<$OpenCL::INTERRUPT->block>. + +=head3 Let yourself be interrupted at any time + +This mode is the default unless AnyEvent is loaded and initialised. In +this mode, OpenCL asynchronously interrupts a running perl program. The +emphasis is on both I and I here. + +Asynchronously means that perl might execute your callbacks at any +time. For example, in the following code (I), +the C loop following the marker call will be interrupted by the +callback: + + my $e = $queue->marker; + my $flag; + $e->cb (sub { $flag = 1 }); + 1 until $flag; + # $flag is now 1 + +The reason why you shouldn't blindly copy the above code is that +busy waiting is a really really bad thing, and really really bad for +performance. + +While at first this asynchronous business might look exciting, it can be +really hard, because you need to be prepared for the callback code to be +executed at any time, which limits the amount of things the callback code +can do safely. + +This can be mitigated somewhat by using C<< +$OpenCL::INTERRUPT->scope_block >> (see the L +documentation for details). + +The other problem is that your program must be actively I to be +interrupted. When you calculate stuff, your program is running. When you +hang in some C functions or other block execution (by calling C, +C