ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/OpenCL/OpenCL.pm
(Generate patch)

Comparing OpenCL/OpenCL.pm (file contents):
Revision 1.59 by root, Wed Apr 25 20:49:13 2012 UTC vs.
Revision 1.75 by root, Sat May 5 02:30:27 2012 UTC

… …
43 43
44OpenCL::Event objects are used to signal when something is complete. 44OpenCL::Event objects are used to signal when something is complete.
45 45
46=head2 HELPFUL RESOURCES 46=head2 HELPFUL RESOURCES
47 47
48The OpenCL specs used to develop this module: 48The OpenCL specs used to develop this module - download these and keept
49hema round, they are required reference material:
49 50
50 http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf 51 http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf
51 http://www.khronos.org/registry/cl/specs/opencl-1.2.pdf 52 http://www.khronos.org/registry/cl/specs/opencl-1.2.pdf
52 http://www.khronos.org/registry/cl/specs/opencl-1.2-extensions.pdf 53 http://www.khronos.org/registry/cl/specs/opencl-1.2-extensions.pdf
53 54
… …
210 211
211 # wait for the last event to complete 212 # wait for the last event to complete
212 $ev->wait; 213 $ev->wait;
213 214
214=head2 Use the OpenGL module to share a texture between OpenCL and OpenGL and draw some julia 215=head2 Use the OpenGL module to share a texture between OpenCL and OpenGL and draw some julia
215set tunnel effect. 216set flight effect.
216 217
217This is quite a long example to get you going. 218This is quite a long example to get you going - you can download it from
219L<http://cvs.schmorp.de/OpenCL/examples/juliaflight>.
218 220
219 use OpenGL ":all"; 221 use OpenGL ":all";
220 use OpenCL; 222 use OpenCL;
221 223
224 my $S = $ARGV[0] || 256; # window/texture size, smaller is faster
225
222 # open a window and create a gl texture 226 # open a window and create a gl texture
223 OpenGL::glpOpenWindow width => 256, height => 256; 227 OpenGL::glpOpenWindow width => $S, height => $S;
224 my $texid = glGenTextures_p 1; 228 my $texid = glGenTextures_p 1;
225 glBindTexture GL_TEXTURE_2D, $texid; 229 glBindTexture GL_TEXTURE_2D, $texid;
226 glTexImage2D_c GL_TEXTURE_2D, 0, GL_RGBA8, 256, 256, 0, GL_RGBA, GL_UNSIGNED_BYTE, 0; 230 glTexImage2D_c GL_TEXTURE_2D, 0, GL_RGBA8, $S, $S, 0, GL_RGBA, GL_UNSIGNED_BYTE, 0;
227 231
228 # find and use the first opencl device that let's us get a shared opengl context 232 # find and use the first opencl device that let's us get a shared opengl context
229 my $platform; 233 my $platform;
230 my $dev; 234 my $dev;
231 my $ctx; 235 my $ctx;
… …
250 # now the boring opencl code 254 # now the boring opencl code
251 my $src = <<EOF; 255 my $src = <<EOF;
252 kernel void 256 kernel void
253 juliatunnel (write_only image2d_t img, float time) 257 juliatunnel (write_only image2d_t img, float time)
254 { 258 {
255 float2 p = (float2)(get_global_id (0), get_global_id (1)) / 256.f * 2.f - 1.f; 259 int2 xy = (int2)(get_global_id (0), get_global_id (1));
260 float2 p = convert_float2 (xy) / $S.f * 2.f - 1.f;
256 261
257 float2 m = (float2)(1.f, p.y) / fabs (p.x); 262 float2 m = (float2)(1.f, p.y) / fabs (p.x); // tunnel
258 m.x = fabs (fmod (m.x + time * 0.05f, 4.f)) - 2.f; 263 m.x = fabs (fmod (m.x + time * 0.05f, 4.f) - 2.f);
259 264
260 float2 z = m; 265 float2 z = m;
261 float2 c = (float2)(sin (time * 0.05005), cos (time * 0.06001)); 266 float2 c = (float2)(sin (time * 0.01133f), cos (time * 0.02521f));
262 267
263 for (int i = 0; i < 25 && dot (z, z) < 4.f; ++i) 268 for (int i = 0; i < 25 && dot (z, z) < 4.f; ++i) // standard julia
264 z = (float2)(z.x * z.x - z.y * z.y, 2.f * z.x * z.y) + c; 269 z = (float2)(z.x * z.x - z.y * z.y, 2.f * z.x * z.y) + c;
265 270
266 float3 colour = (float3)(z.x, z.y, z.x * z.y); 271 float3 colour = (float3)(z.x, z.y, atan2 (z.y, z.x));
267 write_imagef (img, (int2)(get_global_id (0), get_global_id (1)), (float4)(colour * p.x * p.x, 1.)); 272 write_imagef (img, xy, (float4)(colour * p.x * p.x, 1.));
268 } 273 }
269 EOF 274 EOF
270 275
271 my $prog = $ctx->build_program ($src); 276 my $prog = $ctx->build_program ($src);
272 my $kernel = $prog->kernel ("juliatunnel"); 277 my $kernel = $prog->kernel ("juliatunnel");
… …
276 for (my $time; ; ++$time) { 281 for (my $time; ; ++$time) {
277 # acquire objects from opengl 282 # acquire objects from opengl
278 $queue->acquire_gl_objects ([$tex]); 283 $queue->acquire_gl_objects ([$tex]);
279 284
280 # configure and run our kernel 285 # configure and run our kernel
281 $kernel->set_image2d (0, $tex); 286 $kernel->setf ("mf", $tex, $time*2); # mf = memory object, float
282 $kernel->set_float (1, $time);
283 $queue->nd_range_kernel ($kernel, undef, [256, 256], undef); 287 $queue->nd_range_kernel ($kernel, undef, [$S, $S], undef);
284 288
285 # release objects to opengl again 289 # release objects to opengl again
286 $queue->release_gl_objects ([$tex]); 290 $queue->release_gl_objects ([$tex]);
287 291
288 # wait 292 # wait
… …
301 305
302 glXSwapBuffers; 306 glXSwapBuffers;
303 307
304 select undef, undef, undef, 1/60; 308 select undef, undef, undef, 1/60;
305 } 309 }
310
311=head2 How to modify the previous example to not rely on GL sharing.
312
313For those poor souls with only a sucky CPU OpenCL implementation, you
314currently have to read the image into some perl scalar, and then modify a
315texture or use glDrawPixels or so).
316
317First, when you don't need gl sharing, you can create the context much simpler:
318
319 $ctx = $platform->context (undef, [$dev])
320
321To use a texture, you would modify the above example by creating an
322OpenCL::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
326And in the draw loop, intead of acquire_gl_objects/release_gl_objects, you
327would 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
331And 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
335The fully modified example can be found at
336L<http://cvs.schmorp.de/OpenCL/examples/juliaflight-nosharing>.
337
338=head2 Julia sets look soooo 80ies.
339
340Then colour them differently, e.g. using orbit traps! Replace the loop and
341colour 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
353Also try C<-10.f> instead of C<-1.f>.
306 354
307=head1 DOCUMENTATION 355=head1 DOCUMENTATION
308 356
309=head2 BASIC CONVENTIONS 357=head2 BASIC CONVENTIONS
310 358
… …
386OpenCL can generate a number of (potentially) asynchronous events, for 434OpenCL can generate a number of (potentially) asynchronous events, for
387example, after compiling a program, to signal a context-related error or, 435example, after compiling a program, to signal a context-related error or,
388perhaps most important, to signal completion of queued jobs (by setting 436perhaps most important, to signal completion of queued jobs (by setting
389callbacks on OpenCL::Event objects). 437callbacks on OpenCL::Event objects).
390 438
439The OpenCL module converts all these callbacks into events - you can
440still register callbacks, but they are not executed when your OpenCL
441implementation calls the actual callback, but only later. Therefore, none
442of the limitations of OpenCL callbacks apply to the perl implementation:
443it is perfectly safe to make blocking operations from event callbacks, and
444enqueued operations don't need to be flushed.
445
391To facilitate this, this module maintains an event queue - each 446To facilitate this, this module maintains an event queue - each
392time an asynchronous event happens, it is queued, and perl will be 447time an asynchronous event happens, it is queued, and perl will be
393interrupted. This is implemented via the L<Async::Interrupt> module. In 448interrupted. This is implemented via the L<Async::Interrupt> module. In
394addition, this module has L<AnyEvent> support, so it can seamlessly 449addition, this module has L<AnyEvent> support, so it can seamlessly
395integrate itself into many event loops. 450integrate itself into many event loops.
396 451
397Since this module is a bit hard to understand, here are some case examples: 452Since L<Async::Interrupt> is a bit hard to understand, here are some case examples:
398 453
399=head3 Don't use callbacks. 454=head3 Don't use callbacks.
400 455
401When your program never uses any callbacks, then there will never be any 456When your program never uses any callbacks, then there will never be any
402notifications you need to take care of, and therefore no need to worry 457notifications you need to take care of, and therefore no need to worry
… …
493=cut 548=cut
494 549
495package OpenCL; 550package OpenCL;
496 551
497use common::sense; 552use common::sense;
553use Carp ();
498use Async::Interrupt (); 554use Async::Interrupt ();
499 555
500our $POLL_FUNC; # set by XS 556our $POLL_FUNC; # set by XS
501 557
502BEGIN { 558BEGIN {
503 our $VERSION = '0.97'; 559 our $VERSION = '0.99';
504 560
505 require XSLoader; 561 require XSLoader;
506 XSLoader::load (__PACKAGE__, $VERSION); 562 XSLoader::load (__PACKAGE__, $VERSION);
507 563
508 @OpenCL::Platform::ISA = 564 @OpenCL::Platform::ISA =
… …
513 @OpenCL::Sampler::ISA = 569 @OpenCL::Sampler::ISA =
514 @OpenCL::Program::ISA = 570 @OpenCL::Program::ISA =
515 @OpenCL::Kernel::ISA = 571 @OpenCL::Kernel::ISA =
516 @OpenCL::Event::ISA = OpenCL::Object::; 572 @OpenCL::Event::ISA = OpenCL::Object::;
517 573
574 @OpenCL::SubDevice::ISA = OpenCL::Device::;
575
518 @OpenCL::Buffer::ISA = 576 @OpenCL::Buffer::ISA =
519 @OpenCL::Image::ISA = OpenCL::Memory::; 577 @OpenCL::Image::ISA = OpenCL::Memory::;
520 578
521 @OpenCL::BufferObj::ISA = OpenCL::Buffer::; 579 @OpenCL::BufferObj::ISA = OpenCL::Buffer::;
522 580
… …
526 @OpenCL::Image1D::ISA = 584 @OpenCL::Image1D::ISA =
527 @OpenCL::Image1DArray::ISA = 585 @OpenCL::Image1DArray::ISA =
528 @OpenCL::Image1DBuffer::ISA = OpenCL::Image::; 586 @OpenCL::Image1DBuffer::ISA = OpenCL::Image::;
529 587
530 @OpenCL::UserEvent::ISA = OpenCL::Event::; 588 @OpenCL::UserEvent::ISA = OpenCL::Event::;
589
590 @OpenCL::MappedBuffer::ISA =
591 @OpenCL::MappedImage::ISA = OpenCL::Mapped::;
531} 592}
532 593
533=head2 THE OpenCL PACKAGE 594=head2 THE OpenCL PACKAGE
534 595
535=over 4 596=over 4
… …
537=item $int = OpenCL::errno 598=item $int = OpenCL::errno
538 599
539The last error returned by a function - it's only valid after an error occured 600The last error returned by a function - it's only valid after an error occured
540and before calling another OpenCL function. 601and before calling another OpenCL function.
541 602
542=item $str = OpenCL::err2str $errval 603=item $str = OpenCL::err2str [$errval]
543 604
544Comverts an error value into a human readable string. 605Converts an error value into a human readable string. IF no error value is
606given, then the last error will be used (as returned by OpenCL::errno).
545 607
546=item $str = OpenCL::enum2str $enum 608=item $str = OpenCL::enum2str $enum
547 609
548Converts most enum values (of parameter names, image format constants, 610Converts most enum values (of parameter names, image format constants,
549object types, addressing and filter modes, command types etc.) into a 611object types, addressing and filter modes, command types etc.) into a
… …
559 621
560=item $ctx = OpenCL::context_from_type $properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $callback->($err, $pvt) = $print_stderr 622=item $ctx = OpenCL::context_from_type $properties, $type = OpenCL::DEVICE_TYPE_DEFAULT, $callback->($err, $pvt) = $print_stderr
561 623
562Tries to create a context from a default device and platform type - never worked for me. 624Tries to create a context from a default device and platform type - never worked for me.
563 625
626type: OpenCL::DEVICE_TYPE_DEFAULT, OpenCL::DEVICE_TYPE_CPU, OpenCL::DEVICE_TYPE_GPU,
627OpenCL::DEVICE_TYPE_ACCELERATOR, OpenCL::DEVICE_TYPE_CUSTOM, OpenCL::DEVICE_TYPE_ALL.
628
564L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html> 629L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateContextFromType.html>
565 630
566=item $ctx = OpenCL::context $properties, \@devices, $callback->($err, $pvt) = $print_stderr) 631=item $ctx = OpenCL::context $properties, \@devices, $callback->($err, $pvt) = $print_stderr)
567 632
568Create a new OpenCL::Context object using the given device object(s). This 633Create a new OpenCL::Context object using the given device object(s). This
… …
681 746
682=for gengetinfo begin platform 747=for gengetinfo begin platform
683 748
684=item $string = $platform->profile 749=item $string = $platform->profile
685 750
686Calls C<clGetPlatformInfo> with C<CL_PLATFORM_PROFILE> and returns the result. 751Calls C<clGetPlatformInfo> with C<OpenCL::PLATFORM_PROFILE> and returns the result.
687 752
688=item $string = $platform->version 753=item $string = $platform->version
689 754
690Calls C<clGetPlatformInfo> with C<CL_PLATFORM_VERSION> and returns the result. 755Calls C<clGetPlatformInfo> with C<OpenCL::PLATFORM_VERSION> and returns the result.
691 756
692=item $string = $platform->name 757=item $string = $platform->name
693 758
694Calls C<clGetPlatformInfo> with C<CL_PLATFORM_NAME> and returns the result. 759Calls C<clGetPlatformInfo> with C<OpenCL::PLATFORM_NAME> and returns the result.
695 760
696=item $string = $platform->vendor 761=item $string = $platform->vendor
697 762
698Calls C<clGetPlatformInfo> with C<CL_PLATFORM_VENDOR> and returns the result. 763Calls C<clGetPlatformInfo> with C<OpenCL::PLATFORM_VENDOR> and returns the result.
699 764
700=item $string = $platform->extensions 765=item $string = $platform->extensions
701 766
702Calls C<clGetPlatformInfo> with C<CL_PLATFORM_EXTENSIONS> and returns the result. 767Calls C<clGetPlatformInfo> with C<OpenCL::PLATFORM_EXTENSIONS> and returns the result.
703 768
704=for gengetinfo end platform 769=for gengetinfo end platform
705 770
706=back 771=back
707 772
… …
713 778
714See C<< $platform->info >> for details. 779See C<< $platform->info >> for details.
715 780
716L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html> 781L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetDeviceInfo.html>
717 782
783=item @devices = $device->sub_devices (\@properties)
784
785Creates OpencL::SubDevice objects by partitioning an existing device.
786
787L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCreateSubDevices.html>
788
718=for gengetinfo begin device 789=for gengetinfo begin device
719 790
720=item $device_type = $device->type 791=item $device_type = $device->type
721 792
722Calls C<clGetDeviceInfo> with C<CL_DEVICE_TYPE> and returns the result. 793Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_TYPE> and returns the result.
723 794
724=item $uint = $device->vendor_id 795=item $uint = $device->vendor_id
725 796
726Calls C<clGetDeviceInfo> with C<CL_DEVICE_VENDOR_ID> and returns the result. 797Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_VENDOR_ID> and returns the result.
727 798
728=item $uint = $device->max_compute_units 799=item $uint = $device->max_compute_units
729 800
730Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_COMPUTE_UNITS> and returns the result. 801Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_COMPUTE_UNITS> and returns the result.
731 802
732=item $uint = $device->max_work_item_dimensions 803=item $uint = $device->max_work_item_dimensions
733 804
734Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS> and returns the result. 805Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_WORK_ITEM_DIMENSIONS> and returns the result.
735 806
736=item $int = $device->max_work_group_size 807=item $int = $device->max_work_group_size
737 808
738Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_WORK_GROUP_SIZE> and returns the result. 809Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_WORK_GROUP_SIZE> and returns the result.
739 810
740=item @ints = $device->max_work_item_sizes 811=item @ints = $device->max_work_item_sizes
741 812
742Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_WORK_ITEM_SIZES> and returns the result. 813Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_WORK_ITEM_SIZES> and returns the result.
743 814
744=item $uint = $device->preferred_vector_width_char 815=item $uint = $device->preferred_vector_width_char
745 816
746Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR> and returns the result. 817Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PREFERRED_VECTOR_WIDTH_CHAR> and returns the result.
747 818
748=item $uint = $device->preferred_vector_width_short 819=item $uint = $device->preferred_vector_width_short
749 820
750Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT> and returns the result. 821Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PREFERRED_VECTOR_WIDTH_SHORT> and returns the result.
751 822
752=item $uint = $device->preferred_vector_width_int 823=item $uint = $device->preferred_vector_width_int
753 824
754Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT> and returns the result. 825Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PREFERRED_VECTOR_WIDTH_INT> and returns the result.
755 826
756=item $uint = $device->preferred_vector_width_long 827=item $uint = $device->preferred_vector_width_long
757 828
758Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG> and returns the result. 829Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PREFERRED_VECTOR_WIDTH_LONG> and returns the result.
759 830
760=item $uint = $device->preferred_vector_width_float 831=item $uint = $device->preferred_vector_width_float
761 832
762Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT> and returns the result. 833Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT> and returns the result.
763 834
764=item $uint = $device->preferred_vector_width_double 835=item $uint = $device->preferred_vector_width_double
765 836
766Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE> and returns the result. 837Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE> and returns the result.
767 838
768=item $uint = $device->max_clock_frequency 839=item $uint = $device->max_clock_frequency
769 840
770Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_CLOCK_FREQUENCY> and returns the result. 841Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_CLOCK_FREQUENCY> and returns the result.
771 842
772=item $bitfield = $device->address_bits 843=item $bitfield = $device->address_bits
773 844
774Calls C<clGetDeviceInfo> with C<CL_DEVICE_ADDRESS_BITS> and returns the result. 845Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_ADDRESS_BITS> and returns the result.
775 846
776=item $uint = $device->max_read_image_args 847=item $uint = $device->max_read_image_args
777 848
778Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_READ_IMAGE_ARGS> and returns the result. 849Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_READ_IMAGE_ARGS> and returns the result.
779 850
780=item $uint = $device->max_write_image_args 851=item $uint = $device->max_write_image_args
781 852
782Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_WRITE_IMAGE_ARGS> and returns the result. 853Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_WRITE_IMAGE_ARGS> and returns the result.
783 854
784=item $ulong = $device->max_mem_alloc_size 855=item $ulong = $device->max_mem_alloc_size
785 856
786Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_MEM_ALLOC_SIZE> and returns the result. 857Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_MEM_ALLOC_SIZE> and returns the result.
787 858
788=item $int = $device->image2d_max_width 859=item $int = $device->image2d_max_width
789 860
790Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE2D_MAX_WIDTH> and returns the result. 861Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_IMAGE2D_MAX_WIDTH> and returns the result.
791 862
792=item $int = $device->image2d_max_height 863=item $int = $device->image2d_max_height
793 864
794Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE2D_MAX_HEIGHT> and returns the result. 865Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_IMAGE2D_MAX_HEIGHT> and returns the result.
795 866
796=item $int = $device->image3d_max_width 867=item $int = $device->image3d_max_width
797 868
798Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE3D_MAX_WIDTH> and returns the result. 869Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_IMAGE3D_MAX_WIDTH> and returns the result.
799 870
800=item $int = $device->image3d_max_height 871=item $int = $device->image3d_max_height
801 872
802Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE3D_MAX_HEIGHT> and returns the result. 873Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_IMAGE3D_MAX_HEIGHT> and returns the result.
803 874
804=item $int = $device->image3d_max_depth 875=item $int = $device->image3d_max_depth
805 876
806Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE3D_MAX_DEPTH> and returns the result. 877Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_IMAGE3D_MAX_DEPTH> and returns the result.
807 878
808=item $uint = $device->image_support 879=item $uint = $device->image_support
809 880
810Calls C<clGetDeviceInfo> with C<CL_DEVICE_IMAGE_SUPPORT> and returns the result. 881Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_IMAGE_SUPPORT> and returns the result.
811 882
812=item $int = $device->max_parameter_size 883=item $int = $device->max_parameter_size
813 884
814Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_PARAMETER_SIZE> and returns the result. 885Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_PARAMETER_SIZE> and returns the result.
815 886
816=item $uint = $device->max_samplers 887=item $uint = $device->max_samplers
817 888
818Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_SAMPLERS> and returns the result. 889Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_SAMPLERS> and returns the result.
819 890
820=item $uint = $device->mem_base_addr_align 891=item $uint = $device->mem_base_addr_align
821 892
822Calls C<clGetDeviceInfo> with C<CL_DEVICE_MEM_BASE_ADDR_ALIGN> and returns the result. 893Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MEM_BASE_ADDR_ALIGN> and returns the result.
823 894
824=item $uint = $device->min_data_type_align_size 895=item $uint = $device->min_data_type_align_size
825 896
826Calls C<clGetDeviceInfo> with C<CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE> and returns the result. 897Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MIN_DATA_TYPE_ALIGN_SIZE> and returns the result.
827 898
828=item $device_fp_config = $device->single_fp_config 899=item $device_fp_config = $device->single_fp_config
829 900
830Calls C<clGetDeviceInfo> with C<CL_DEVICE_SINGLE_FP_CONFIG> and returns the result. 901Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_SINGLE_FP_CONFIG> and returns the result.
831 902
832=item $device_mem_cache_type = $device->global_mem_cache_type 903=item $device_mem_cache_type = $device->global_mem_cache_type
833 904
834Calls C<clGetDeviceInfo> with C<CL_DEVICE_GLOBAL_MEM_CACHE_TYPE> and returns the result. 905Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_GLOBAL_MEM_CACHE_TYPE> and returns the result.
835 906
836=item $uint = $device->global_mem_cacheline_size 907=item $uint = $device->global_mem_cacheline_size
837 908
838Calls C<clGetDeviceInfo> with C<CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE> and returns the result. 909Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_GLOBAL_MEM_CACHELINE_SIZE> and returns the result.
839 910
840=item $ulong = $device->global_mem_cache_size 911=item $ulong = $device->global_mem_cache_size
841 912
842Calls C<clGetDeviceInfo> with C<CL_DEVICE_GLOBAL_MEM_CACHE_SIZE> and returns the result. 913Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_GLOBAL_MEM_CACHE_SIZE> and returns the result.
843 914
844=item $ulong = $device->global_mem_size 915=item $ulong = $device->global_mem_size
845 916
846Calls C<clGetDeviceInfo> with C<CL_DEVICE_GLOBAL_MEM_SIZE> and returns the result. 917Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_GLOBAL_MEM_SIZE> and returns the result.
847 918
848=item $ulong = $device->max_constant_buffer_size 919=item $ulong = $device->max_constant_buffer_size
849 920
850Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE> and returns the result. 921Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_CONSTANT_BUFFER_SIZE> and returns the result.
851 922
852=item $uint = $device->max_constant_args 923=item $uint = $device->max_constant_args
853 924
854Calls C<clGetDeviceInfo> with C<CL_DEVICE_MAX_CONSTANT_ARGS> and returns the result. 925Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_MAX_CONSTANT_ARGS> and returns the result.
855 926
856=item $device_local_mem_type = $device->local_mem_type 927=item $device_local_mem_type = $device->local_mem_type
857 928
858Calls C<clGetDeviceInfo> with C<CL_DEVICE_LOCAL_MEM_TYPE> and returns the result. 929Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_LOCAL_MEM_TYPE> and returns the result.
859 930
860=item $ulong = $device->local_mem_size 931=item $ulong = $device->local_mem_size
861 932
862Calls C<clGetDeviceInfo> with C<CL_DEVICE_LOCAL_MEM_SIZE> and returns the result. 933Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_LOCAL_MEM_SIZE> and returns the result.
863 934
864=item $boolean = $device->error_correction_support 935=item $boolean = $device->error_correction_support
865 936
866Calls C<clGetDeviceInfo> with C<CL_DEVICE_ERROR_CORRECTION_SUPPORT> and returns the result. 937Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_ERROR_CORRECTION_SUPPORT> and returns the result.
867 938
868=item $int = $device->profiling_timer_resolution 939=item $int = $device->profiling_timer_resolution
869 940
870Calls C<clGetDeviceInfo> with C<CL_DEVICE_PROFILING_TIMER_RESOLUTION> and returns the result. 941Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PROFILING_TIMER_RESOLUTION> and returns the result.
871 942
872=item $boolean = $device->endian_little 943=item $boolean = $device->endian_little
873 944
874Calls C<clGetDeviceInfo> with C<CL_DEVICE_ENDIAN_LITTLE> and returns the result. 945Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_ENDIAN_LITTLE> and returns the result.
875 946
876=item $boolean = $device->available 947=item $boolean = $device->available
877 948
878Calls C<clGetDeviceInfo> with C<CL_DEVICE_AVAILABLE> and returns the result. 949Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_AVAILABLE> and returns the result.
879 950
880=item $boolean = $device->compiler_available 951=item $boolean = $device->compiler_available
881 952
882Calls C<clGetDeviceInfo> with C<CL_DEVICE_COMPILER_AVAILABLE> and returns the result. 953Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_COMPILER_AVAILABLE> and returns the result.
883 954
884=item $device_exec_capabilities = $device->execution_capabilities 955=item $device_exec_capabilities = $device->execution_capabilities
885 956
886Calls C<clGetDeviceInfo> with C<CL_DEVICE_EXECUTION_CAPABILITIES> and returns the result. 957Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_EXECUTION_CAPABILITIES> and returns the result.
887 958
888=item $command_queue_properties = $device->properties 959=item $command_queue_properties = $device->properties
889 960
890Calls C<clGetDeviceInfo> with C<CL_DEVICE_QUEUE_PROPERTIES> and returns the result. 961Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_QUEUE_PROPERTIES> and returns the result.
891 962
892=item $ = $device->platform 963=item $ = $device->platform
893 964
894Calls C<clGetDeviceInfo> with C<CL_DEVICE_PLATFORM> and returns the result. 965Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PLATFORM> and returns the result.
895 966
896=item $string = $device->name 967=item $string = $device->name
897 968
898Calls C<clGetDeviceInfo> with C<CL_DEVICE_NAME> and returns the result. 969Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_NAME> and returns the result.
899 970
900=item $string = $device->vendor 971=item $string = $device->vendor
901 972
902Calls C<clGetDeviceInfo> with C<CL_DEVICE_VENDOR> and returns the result. 973Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_VENDOR> and returns the result.
903 974
904=item $string = $device->driver_version 975=item $string = $device->driver_version
905 976
906Calls C<clGetDeviceInfo> with C<CL_DRIVER_VERSION> and returns the result. 977Calls C<clGetDeviceInfo> with C<OpenCL::DRIVER_VERSION> and returns the result.
907 978
908=item $string = $device->profile 979=item $string = $device->profile
909 980
910Calls C<clGetDeviceInfo> with C<CL_DEVICE_PROFILE> and returns the result. 981Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PROFILE> and returns the result.
911 982
912=item $string = $device->version 983=item $string = $device->version
913 984
914Calls C<clGetDeviceInfo> with C<CL_DEVICE_VERSION> and returns the result. 985Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_VERSION> and returns the result.
915 986
916=item $string = $device->extensions 987=item $string = $device->extensions
917 988
918Calls C<clGetDeviceInfo> with C<CL_DEVICE_EXTENSIONS> and returns the result. 989Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_EXTENSIONS> and returns the result.
919 990
920=item $uint = $device->preferred_vector_width_half 991=item $uint = $device->preferred_vector_width_half
921 992
922Calls C<clGetDeviceInfo> with C<CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF> and returns the result. 993Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PREFERRED_VECTOR_WIDTH_HALF> and returns the result.
923 994
924=item $uint = $device->native_vector_width_char 995=item $uint = $device->native_vector_width_char
925 996
926Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_CHAR> and returns the result. 997Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_NATIVE_VECTOR_WIDTH_CHAR> and returns the result.
927 998
928=item $uint = $device->native_vector_width_short 999=item $uint = $device->native_vector_width_short
929 1000
930Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_SHORT> and returns the result. 1001Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_NATIVE_VECTOR_WIDTH_SHORT> and returns the result.
931 1002
932=item $uint = $device->native_vector_width_int 1003=item $uint = $device->native_vector_width_int
933 1004
934Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_INT> and returns the result. 1005Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_NATIVE_VECTOR_WIDTH_INT> and returns the result.
935 1006
936=item $uint = $device->native_vector_width_long 1007=item $uint = $device->native_vector_width_long
937 1008
938Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_LONG> and returns the result. 1009Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_NATIVE_VECTOR_WIDTH_LONG> and returns the result.
939 1010
940=item $uint = $device->native_vector_width_float 1011=item $uint = $device->native_vector_width_float
941 1012
942Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_FLOAT> and returns the result. 1013Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_NATIVE_VECTOR_WIDTH_FLOAT> and returns the result.
943 1014
944=item $uint = $device->native_vector_width_double 1015=item $uint = $device->native_vector_width_double
945 1016
946Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE> and returns the result. 1017Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE> and returns the result.
947 1018
948=item $uint = $device->native_vector_width_half 1019=item $uint = $device->native_vector_width_half
949 1020
950Calls C<clGetDeviceInfo> with C<CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF> and returns the result. 1021Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_NATIVE_VECTOR_WIDTH_HALF> and returns the result.
951 1022
952=item $device_fp_config = $device->double_fp_config 1023=item $device_fp_config = $device->double_fp_config
953 1024
954Calls C<clGetDeviceInfo> with C<CL_DEVICE_DOUBLE_FP_CONFIG> and returns the result. 1025Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_DOUBLE_FP_CONFIG> and returns the result.
955 1026
956=item $device_fp_config = $device->half_fp_config 1027=item $device_fp_config = $device->half_fp_config
957 1028
958Calls C<clGetDeviceInfo> with C<CL_DEVICE_HALF_FP_CONFIG> and returns the result. 1029Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_HALF_FP_CONFIG> and returns the result.
959 1030
960=item $boolean = $device->host_unified_memory 1031=item $boolean = $device->host_unified_memory
961 1032
962Calls C<clGetDeviceInfo> with C<CL_DEVICE_HOST_UNIFIED_MEMORY> and returns the result. 1033Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_HOST_UNIFIED_MEMORY> and returns the result.
963 1034
964=item $device = $device->parent_device_ext 1035=item $device = $device->parent_device_ext
965 1036
966Calls C<clGetDeviceInfo> with C<CL_DEVICE_PARENT_DEVICE_EXT> and returns the result. 1037Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PARENT_DEVICE_EXT> and returns the result.
967 1038
968=item @device_partition_property_exts = $device->partition_types_ext 1039=item @device_partition_property_exts = $device->partition_types_ext
969 1040
970Calls C<clGetDeviceInfo> with C<CL_DEVICE_PARTITION_TYPES_EXT> and returns the result. 1041Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PARTITION_TYPES_EXT> and returns the result.
971 1042
972=item @device_partition_property_exts = $device->affinity_domains_ext 1043=item @device_partition_property_exts = $device->affinity_domains_ext
973 1044
974Calls C<clGetDeviceInfo> with C<CL_DEVICE_AFFINITY_DOMAINS_EXT> and returns the result. 1045Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_AFFINITY_DOMAINS_EXT> and returns the result.
975 1046
976=item $uint = $device->reference_count_ext 1047=item $uint = $device->reference_count_ext
977 1048
978Calls C<clGetDeviceInfo> with C<CL_DEVICE_REFERENCE_COUNT_EXT> and returns the result. 1049Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_REFERENCE_COUNT_EXT> and returns the result.
979 1050
980=item @device_partition_property_exts = $device->partition_style_ext 1051=item @device_partition_property_exts = $device->partition_style_ext
981 1052
982Calls C<clGetDeviceInfo> with C<CL_DEVICE_PARTITION_STYLE_EXT> and returns the result. 1053Calls C<clGetDeviceInfo> with C<OpenCL::DEVICE_PARTITION_STYLE_EXT> and returns the result.
983 1054
984=for gengetinfo end device 1055=for gengetinfo end device
985 1056
986=back 1057=back
987 1058
988=head2 THE OpenCL::Context CLASS 1059=head2 THE OpenCL::Context CLASS
1060
1061An OpenCL::Context is basically a container, or manager, for a number of
1062devices of a platform. It is used to create all sorts of secondary objects
1063such as buffers, queues, programs and so on.
1064
1065All context creation functions and methods take a list of properties
1066(type-value pairs). All property values can be specified as integers -
1067some additionally support other types:
1068
1069=over 4
1070
1071=item OpenCL::CONTEXT_PLATFORM
1072
1073Also accepts OpenCL::Platform objects.
1074
1075=item OpenCL::GLX_DISPLAY_KHR
1076
1077Also accepts C<undef>, in which case a deep and troubling hack is engaged
1078to find the current glx display (see L<GLX SUPPORT>).
1079
1080=item OpenCL::GL_CONTEXT_KHR
1081
1082Also accepts C<undef>, in which case a deep and troubling hack is engaged
1083to find the current glx context (see L<GLX SUPPORT>).
1084
1085=back
989 1086
990=over 4 1087=over 4
991 1088
992=item $prog = $ctx->build_program ($program, $options = "") 1089=item $prog = $ctx->build_program ($program, $options = "")
993 1090
… …
1002=cut 1099=cut
1003 1100
1004sub OpenCL::Context::build_program { 1101sub OpenCL::Context::build_program {
1005 my ($self, $prog, $options) = @_; 1102 my ($self, $prog, $options) = @_;
1006 1103
1007 require Carp;
1008
1009 $prog = $self->program_with_source ($prog) 1104 $prog = $self->program_with_source ($prog)
1010 unless ref $prog; 1105 unless ref $prog;
1011 1106
1012 # we build separately per device so we instantly know which one failed 1107 eval { $prog->build (undef, $options); 1 }
1108 or errno == BUILD_PROGRAM_FAILURE
1109 or errno == INVALID_BINARY # workaround nvidia bug
1110 or Carp::croak "OpenCL::Context->build_program: " . err2str;
1111
1112 # we check status for all devices
1013 for my $dev ($self->devices) { 1113 for my $dev ($self->devices) {
1014 eval { $prog->build ([$dev], $options); 1 } 1114 $prog->build_status ($dev) == BUILD_SUCCESS
1015 or Carp::croak ("Building OpenCL program for device '" . $dev->name . "' failed:\n" 1115 or Carp::croak "Building OpenCL program for device '" . $dev->name . "' failed:\n"
1016 . $prog->build_log ($dev)); 1116 . $prog->build_log ($dev);
1017 } 1117 }
1018 1118
1019 $prog 1119 $prog
1020} 1120}
1021 1121
… …
1038=item $buf = $ctx->buffer ($flags, $len) 1138=item $buf = $ctx->buffer ($flags, $len)
1039 1139
1040Creates a new OpenCL::Buffer (actually OpenCL::BufferObj) object with the 1140Creates a new OpenCL::Buffer (actually OpenCL::BufferObj) object with the
1041given flags and octet-size. 1141given flags and octet-size.
1042 1142
1143flags: OpenCL::MEM_READ_WRITE, OpenCL::MEM_WRITE_ONLY, OpenCL::MEM_READ_ONLY,
1144OpenCL::MEM_USE_HOST_PTR, OpenCL::MEM_ALLOC_HOST_PTR, OpenCL::MEM_COPY_HOST_PTR,
1145OpenCL::MEM_HOST_WRITE_ONLY, OpenCL::MEM_HOST_READ_ONLY, OpenCL::MEM_HOST_NO_ACCESS.
1146
1043L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateBuffer.html> 1147L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateBuffer.html>
1044 1148
1045=item $buf = $ctx->buffer_sv ($flags, $data) 1149=item $buf = $ctx->buffer_sv ($flags, $data)
1046 1150
1047Creates a new OpenCL::Buffer (actually OpenCL::BufferObj) object and 1151Creates a new OpenCL::Buffer (actually OpenCL::BufferObj) object and
… …
1050=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) 1154=item $img = $ctx->image ($self, $flags, $channel_order, $channel_type, $type, $width, $height, $depth = 0, $array_size = 0, $row_pitch = 0, $slice_pitch = 0, $num_mip_level = 0, $num_samples = 0, $*data = &PL_sv_undef)
1051 1155
1052Creates a new OpenCL::Image object and optionally initialises it with 1156Creates a new OpenCL::Image object and optionally initialises it with
1053the given data values. 1157the given data values.
1054 1158
1159channel_order: OpenCL::R, OpenCL::A, OpenCL::RG, OpenCL::RA, OpenCL::RGB,
1160OpenCL::RGBA, OpenCL::BGRA, OpenCL::ARGB, OpenCL::INTENSITY, OpenCL::LUMINANCE,
1161OpenCL::Rx, OpenCL::RGx, OpenCL::RGBx.
1162
1163channel_type: OpenCL::SNORM_INT8, OpenCL::SNORM_INT16, OpenCL::UNORM_INT8,
1164OpenCL::UNORM_INT16, OpenCL::UNORM_SHORT_565, OpenCL::UNORM_SHORT_555,
1165OpenCL::UNORM_INT_101010, OpenCL::SIGNED_INT8, OpenCL::SIGNED_INT16,
1166OpenCL::SIGNED_INT32, OpenCL::UNSIGNED_INT8, OpenCL::UNSIGNED_INT16,
1167OpenCL::UNSIGNED_INT32, OpenCL::HALF_FLOAT, OpenCL::FLOAT.
1168
1169
1170type: OpenCL::MEM_OBJECT_BUFFER, OpenCL::MEM_OBJECT_IMAGE2D,
1171OpenCL::MEM_OBJECT_IMAGE3D, OpenCL::MEM_OBJECT_IMAGE2D_ARRAY,
1172OpenCL::MEM_OBJECT_IMAGE1D, OpenCL::MEM_OBJECT_IMAGE1D_ARRAY,
1173OpenCL::MEM_OBJECT_IMAGE1D_BUFFER.
1174
1055L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCreateImage.html> 1175L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCreateImage.html>
1056 1176
1057=item $img = $ctx->image2d ($flags, $channel_order, $channel_type, $width, $height, $row_pitch = 0, $data = undef) 1177=item $img = $ctx->image2d ($flags, $channel_order, $channel_type, $width, $height, $row_pitch = 0, $data = undef)
1058 1178
1059Creates a new OpenCL::Image2D object and optionally initialises it with 1179Creates a new OpenCL::Image2D object and optionally initialises it with
… …
1071=item $buffer = $ctx->gl_buffer ($flags, $bufobj) 1191=item $buffer = $ctx->gl_buffer ($flags, $bufobj)
1072 1192
1073Creates a new OpenCL::Buffer (actually OpenCL::BufferObj) object that refers to the given 1193Creates a new OpenCL::Buffer (actually OpenCL::BufferObj) object that refers to the given
1074OpenGL buffer object. 1194OpenGL buffer object.
1075 1195
1196flags: OpenCL::MEM_READ_WRITE, OpenCL::MEM_READ_ONLY, OpenCL::MEM_WRITE_ONLY.
1197
1076http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateFromGLBuffer.html 1198http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateFromGLBuffer.html
1077 1199
1078=item $img = $ctx->gl_texture ($flags, $target, $miplevel, $texture) 1200=item $img = $ctx->gl_texture ($flags, $target, $miplevel, $texture)
1079 1201
1080Creates a new OpenCL::Image object that refers to the given OpenGL 1202Creates a new OpenCL::Image object that refers to the given OpenGL
1081texture object or buffer. 1203texture object or buffer.
1082 1204
1205target: GL_TEXTURE_1D, GL_TEXTURE_1D_ARRAY, GL_TEXTURE_BUFFER,
1206GL_TEXTURE_2D, GL_TEXTURE_2D_ARRAY, GL_TEXTURE_3D,
1207GL_TEXTURE_CUBE_MAP_POSITIVE_X, GL_TEXTURE_CUBE_MAP_POSITIVE_Y,
1208GL_TEXTURE_CUBE_MAP_POSITIVE_Z, GL_TEXTURE_CUBE_MAP_NEGATIVE_X,
1209GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, GL_TEXTURE_CUBE_MAP_NEGATIVE_Z,
1210GL_TEXTURE_RECTANGLE/GL_TEXTURE_RECTANGLE_ARB.
1211
1083http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCreateFromGLTexture.html 1212http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCreateFromGLTexture.html
1084 1213
1085=item $img = $ctx->gl_texture2d ($flags, $target, $miplevel, $texture) 1214=item $img = $ctx->gl_texture2d ($flags, $target, $miplevel, $texture)
1086 1215
1087Creates a new OpenCL::Image2D object that refers to the given OpenGL 1216Creates a new OpenCL::Image2D object that refers to the given OpenGL
… …
1112 1241
1113=item $sampler = $ctx->sampler ($normalized_coords, $addressing_mode, $filter_mode) 1242=item $sampler = $ctx->sampler ($normalized_coords, $addressing_mode, $filter_mode)
1114 1243
1115Creates a new OpenCL::Sampler object. 1244Creates a new OpenCL::Sampler object.
1116 1245
1246addressing_mode: OpenCL::ADDRESS_NONE, OpenCL::ADDRESS_CLAMP_TO_EDGE,
1247OpenCL::ADDRESS_CLAMP, OpenCL::ADDRESS_REPEAT, OpenCL::ADDRESS_MIRRORED_REPEAT.
1248
1249filter_mode: OpenCL::FILTER_NEAREST, OpenCL::FILTER_LINEAR.
1250
1117L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateSampler.html> 1251L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateSampler.html>
1118 1252
1119=item $program = $ctx->program_with_source ($string) 1253=item $program = $ctx->program_with_source ($string)
1120 1254
1121Creates a new OpenCL::Program object from the given source code. 1255Creates a new OpenCL::Program object from the given source code.
1122 1256
1123L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateProgramWithSource.html> 1257L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateProgramWithSource.html>
1124 1258
1259=item ($program, \@status) = $ctx->program_with_binary (\@devices, \@binaries)
1260
1261Creates a new OpenCL::Program object from the given binaries.
1262
1263L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clCreateProgramWithBinary.html>
1264
1265Example: clone an existing program object that contains a successfully
1266compiled program, no matter how useless this is.
1267
1268 my $clone = $ctx->program_with_binary ([$prog->devices], [$prog->binaries]);
1269
1270=item $program = $ctx->program_with_built_in_kernels (\@devices, $kernel_names)
1271
1272Creates a new OpenCL::Program object from the given built-in kernel names.
1273
1274L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCreateProgramWithBuiltInKernels.html>
1275
1276=item $program = $ctx->link_program (\@devices, $options, \@programs, $cb->($program) = undef)
1277
1278Links all (already compiled) program objects specified in C<@programs>
1279together and returns a new OpenCL::Program object with the result.
1280
1281L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clLinkProgram.html>
1282
1125=item $packed_value = $ctx->info ($name) 1283=item $packed_value = $ctx->info ($name)
1126 1284
1127See C<< $platform->info >> for details. 1285See C<< $platform->info >> for details.
1128 1286
1129L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html> 1287L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetContextInfo.html>
1130 1288
1131=for gengetinfo begin context 1289=for gengetinfo begin context
1132 1290
1133=item $uint = $context->reference_count 1291=item $uint = $context->reference_count
1134 1292
1135Calls C<clGetContextInfo> with C<CL_CONTEXT_REFERENCE_COUNT> and returns the result. 1293Calls C<clGetContextInfo> with C<OpenCL::CONTEXT_REFERENCE_COUNT> and returns the result.
1136 1294
1137=item @devices = $context->devices 1295=item @devices = $context->devices
1138 1296
1139Calls C<clGetContextInfo> with C<CL_CONTEXT_DEVICES> and returns the result. 1297Calls C<clGetContextInfo> with C<OpenCL::CONTEXT_DEVICES> and returns the result.
1140 1298
1141=item @property_ints = $context->properties 1299=item @property_ints = $context->properties
1142 1300
1143Calls C<clGetContextInfo> with C<CL_CONTEXT_PROPERTIES> and returns the result. 1301Calls C<clGetContextInfo> with C<OpenCL::CONTEXT_PROPERTIES> and returns the result.
1144 1302
1145=item $uint = $context->num_devices 1303=item $uint = $context->num_devices
1146 1304
1147Calls C<clGetContextInfo> with C<CL_CONTEXT_NUM_DEVICES> and returns the result. 1305Calls C<clGetContextInfo> with C<OpenCL::CONTEXT_NUM_DEVICES> and returns the result.
1148 1306
1149=for gengetinfo end context 1307=for gengetinfo end context
1150 1308
1151=back 1309=back
1152 1310
… …
1199 1357
1200=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...) 1358=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...)
1201 1359
1202http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteBufferRect.html 1360http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteBufferRect.html
1203 1361
1362=item $ev = $queue->copy_buffer_to_image ($src_buffer, $dst_image, $src_offset, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $wait_events...)
1363
1364L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferToImage.html>
1365
1204=item $ev = $queue->read_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...) 1366=item $ev = $queue->read_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...)
1205 1367
1206L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyBufferRect.html> 1368C<$row_pitch> (and C<$slice_pitch>) can be C<0>, in which case the OpenCL
1207 1369module uses the image width (and height) to supply default values.
1208=item $ev = $queue->copy_buffer_to_image ($src_buffer, $dst_image, $src_offset, $dst_x, $dst_y, $dst_z, $width, $height, $depth, $wait_events...)
1209 1370
1210L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadImage.html> 1371L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadImage.html>
1211 1372
1212=item $ev = $queue->write_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...) 1373=item $ev = $queue->write_image ($src, $blocking, $x, $y, $z, $width, $height, $depth, $row_pitch, $slice_pitch, $data, $wait_events...)
1213 1374
1375C<$row_pitch> (and C<$slice_pitch>) can be C<0>, in which case the OpenCL
1376module uses the image width (and height) to supply default values.
1214L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteImage.html> 1377L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteImage.html>
1215 1378
1216=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...) 1379=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...)
1217 1380
1218L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImage.html> 1381L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueCopyImage.html>
… …
1263reference to an array of local work sizes, with the same number of 1426reference to an array of local work sizes, with the same number of
1264elements as \@global_work_size. 1427elements as \@global_work_size.
1265 1428
1266L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueNDRangeKernel.html> 1429L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueNDRangeKernel.html>
1267 1430
1431=item $ev = $queue->migrate_mem_objects (\@mem_objects, $flags, $wait_events...)
1432
1433Migrates a number of OpenCL::Memory objects to or from the device.
1434
1435flags: OpenCL::MIGRATE_MEM_OBJECT_HOST, OpenCL::MIGRATE_MEM_OBJECT_CONTENT_UNDEFINED
1436
1437L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clEnqueueMigrateMemObjects.html>
1438
1268=item $ev = $queue->acquire_gl_objects ([object, ...], $wait_events...) 1439=item $ev = $queue->acquire_gl_objects ([object, ...], $wait_events...)
1269 1440
1270Enqueues a list (an array-ref of OpenCL::Memory objects) to be acquired 1441Enqueues a list (an array-ref of OpenCL::Memory objects) to be acquired
1271for subsequent OpenCL usage. 1442for subsequent OpenCL usage.
1272 1443
… …
1307 1478
1308=for gengetinfo begin command_queue 1479=for gengetinfo begin command_queue
1309 1480
1310=item $ctx = $command_queue->context 1481=item $ctx = $command_queue->context
1311 1482
1312Calls C<clGetCommandQueueInfo> with C<CL_QUEUE_CONTEXT> and returns the result. 1483Calls C<clGetCommandQueueInfo> with C<OpenCL::QUEUE_CONTEXT> and returns the result.
1313 1484
1314=item $device = $command_queue->device 1485=item $device = $command_queue->device
1315 1486
1316Calls C<clGetCommandQueueInfo> with C<CL_QUEUE_DEVICE> and returns the result. 1487Calls C<clGetCommandQueueInfo> with C<OpenCL::QUEUE_DEVICE> and returns the result.
1317 1488
1318=item $uint = $command_queue->reference_count 1489=item $uint = $command_queue->reference_count
1319 1490
1320Calls C<clGetCommandQueueInfo> with C<CL_QUEUE_REFERENCE_COUNT> and returns the result. 1491Calls C<clGetCommandQueueInfo> with C<OpenCL::QUEUE_REFERENCE_COUNT> and returns the result.
1321 1492
1322=item $command_queue_properties = $command_queue->properties 1493=item $command_queue_properties = $command_queue->properties
1323 1494
1324Calls C<clGetCommandQueueInfo> with C<CL_QUEUE_PROPERTIES> and returns the result. 1495Calls C<clGetCommandQueueInfo> with C<OpenCL::QUEUE_PROPERTIES> and returns the result.
1325 1496
1326=for gengetinfo end command_queue 1497=for gengetinfo end command_queue
1498
1499=back
1500
1501=head3 MEMORY MAPPED BUFFERS
1502
1503OpenCL allows you to map buffers and images to host memory (read: perl
1504scalars). This is done much like reading or copying a buffer, by enqueuing
1505a map or unmap operation on the command queue.
1506
1507The map operations return an C<OpenCL::Mapped> object - see L<THE
1508OpenCL::Mapped CLASS> section for details on what to do with these
1509objects.
1510
1511The object will be unmapped automatically when the mapped object is
1512destroyed (you can use a barrier to make sure the unmap has finished,
1513before using the buffer in a kernel), but you can also enqueue an unmap
1514operation manually.
1515
1516=over 4
1517
1518=item $mapped_buffer = $queue->map_buffer ($buf, $blocking=1, $map_flags=OpenCL::MAP_READ|OpenCL::MAP_WRITE, $offset=0, $size=undef, $wait_events...)
1519
1520Maps the given buffer into host memory and returns an
1521C<OpenCL::MappedBuffer> object. If C<$size> is specified as undef, then
1522the map will extend to the end of the buffer.
1523
1524map_flags: OpenCL::MAP_READ, OpenCL::MAP_WRITE, OpenCL::MAP_WRITE_INVALIDATE_REGION.
1525
1526L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueMapBuffer.html>
1527
1528Example: map the buffer $buf fully and replace the first 4 bytes by "abcd", then unmap.
1529
1530 {
1531 my $mapped = $queue->map_buffer ($buf, 1, OpenCL::MAP_WRITE);
1532 substr $$mapped, 0, 4, "abcd";
1533 } # asynchronously unmap because $mapped is destroyed
1534
1535=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...)
1536
1537Maps the given image area into host memory and return an
1538C<OpenCL::MappedImage> object.
1539
1540If any of C<$width>, C<$height> and/or C<$depth> are C<undef> then they
1541will be replaced by the maximum possible value.
1542
1543L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueMapImage.html>
1544
1545Example: map an image (with OpenCL::UNSIGNED_INT8 channel type) and set
1546the first channel of the leftmost column to 5, then explicitly unmap
1547it. You are not necessarily meant to do it this way, this example just
1548shows you the accessors to use :)
1549
1550 my $mapped = $queue->map_image ($image, 1, OpenCL::MAP_WRITE);
1551
1552 $mapped->set ($_ * $mapped->row_pitch, pack "C", 5)
1553 for 0..$image->height;
1554
1555 $mapped->unmap;.
1556 $mapped->wait; # only needed for out of order queues normally
1557
1558=item $ev = $queue->unmap ($mapped, $wait_events...)
1559
1560Unmaps the data from host memory. You must not call any methods that
1561modify the data, or modify the data scalar directly, after calling this
1562method.
1563
1564The mapped event object will always be passed as part of the
1565$wait_events. The mapped event object will be replaced by the new event
1566object that this request creates.
1327 1567
1328=back 1568=back
1329 1569
1330=head2 THE OpenCL::Memory CLASS 1570=head2 THE OpenCL::Memory CLASS
1331 1571
… …
1342 1582
1343=for gengetinfo begin mem 1583=for gengetinfo begin mem
1344 1584
1345=item $mem_object_type = $mem->type 1585=item $mem_object_type = $mem->type
1346 1586
1347Calls C<clGetMemObjectInfo> with C<CL_MEM_TYPE> and returns the result. 1587Calls C<clGetMemObjectInfo> with C<OpenCL::MEM_TYPE> and returns the result.
1348 1588
1349=item $mem_flags = $mem->flags 1589=item $mem_flags = $mem->flags
1350 1590
1351Calls C<clGetMemObjectInfo> with C<CL_MEM_FLAGS> and returns the result. 1591Calls C<clGetMemObjectInfo> with C<OpenCL::MEM_FLAGS> and returns the result.
1352 1592
1353=item $int = $mem->size 1593=item $int = $mem->size
1354 1594
1355Calls C<clGetMemObjectInfo> with C<CL_MEM_SIZE> and returns the result. 1595Calls C<clGetMemObjectInfo> with C<OpenCL::MEM_SIZE> and returns the result.
1356 1596
1357=item $ptr_value = $mem->host_ptr 1597=item $ptr_value = $mem->host_ptr
1358 1598
1359Calls C<clGetMemObjectInfo> with C<CL_MEM_HOST_PTR> and returns the result. 1599Calls C<clGetMemObjectInfo> with C<OpenCL::MEM_HOST_PTR> and returns the result.
1360 1600
1361=item $uint = $mem->map_count 1601=item $uint = $mem->map_count
1362 1602
1363Calls C<clGetMemObjectInfo> with C<CL_MEM_MAP_COUNT> and returns the result. 1603Calls C<clGetMemObjectInfo> with C<OpenCL::MEM_MAP_COUNT> and returns the result.
1364 1604
1365=item $uint = $mem->reference_count 1605=item $uint = $mem->reference_count
1366 1606
1367Calls C<clGetMemObjectInfo> with C<CL_MEM_REFERENCE_COUNT> and returns the result. 1607Calls C<clGetMemObjectInfo> with C<OpenCL::MEM_REFERENCE_COUNT> and returns the result.
1368 1608
1369=item $ctx = $mem->context 1609=item $ctx = $mem->context
1370 1610
1371Calls C<clGetMemObjectInfo> with C<CL_MEM_CONTEXT> and returns the result. 1611Calls C<clGetMemObjectInfo> with C<OpenCL::MEM_CONTEXT> and returns the result.
1372 1612
1373=item $mem = $mem->associated_memobject 1613=item $mem = $mem->associated_memobject
1374 1614
1375Calls C<clGetMemObjectInfo> with C<CL_MEM_ASSOCIATED_MEMOBJECT> and returns the result. 1615Calls C<clGetMemObjectInfo> with C<OpenCL::MEM_ASSOCIATED_MEMOBJECT> and returns the result.
1376 1616
1377=item $int = $mem->offset 1617=item $int = $mem->offset
1378 1618
1379Calls C<clGetMemObjectInfo> with C<CL_MEM_OFFSET> and returns the result. 1619Calls C<clGetMemObjectInfo> with C<OpenCL::MEM_OFFSET> and returns the result.
1380 1620
1381=for gengetinfo end mem 1621=for gengetinfo end mem
1382 1622
1383=item ($type, $name) = $mem->gl_object_info 1623=item ($type, $name) = $mem->gl_object_info
1384 1624
… …
1436 1676
1437=for gengetinfo begin image 1677=for gengetinfo begin image
1438 1678
1439=item $int = $image->element_size 1679=item $int = $image->element_size
1440 1680
1441Calls C<clGetImageInfo> with C<CL_IMAGE_ELEMENT_SIZE> and returns the result. 1681Calls C<clGetImageInfo> with C<OpenCL::IMAGE_ELEMENT_SIZE> and returns the result.
1442 1682
1443=item $int = $image->row_pitch 1683=item $int = $image->row_pitch
1444 1684
1445Calls C<clGetImageInfo> with C<CL_IMAGE_ROW_PITCH> and returns the result. 1685Calls C<clGetImageInfo> with C<OpenCL::IMAGE_ROW_PITCH> and returns the result.
1446 1686
1447=item $int = $image->slice_pitch 1687=item $int = $image->slice_pitch
1448 1688
1449Calls C<clGetImageInfo> with C<CL_IMAGE_SLICE_PITCH> and returns the result. 1689Calls C<clGetImageInfo> with C<OpenCL::IMAGE_SLICE_PITCH> and returns the result.
1450 1690
1451=item $int = $image->width 1691=item $int = $image->width
1452 1692
1453Calls C<clGetImageInfo> with C<CL_IMAGE_WIDTH> and returns the result. 1693Calls C<clGetImageInfo> with C<OpenCL::IMAGE_WIDTH> and returns the result.
1454 1694
1455=item $int = $image->height 1695=item $int = $image->height
1456 1696
1457Calls C<clGetImageInfo> with C<CL_IMAGE_HEIGHT> and returns the result. 1697Calls C<clGetImageInfo> with C<OpenCL::IMAGE_HEIGHT> and returns the result.
1458 1698
1459=item $int = $image->depth 1699=item $int = $image->depth
1460 1700
1461Calls C<clGetImageInfo> with C<CL_IMAGE_DEPTH> and returns the result. 1701Calls C<clGetImageInfo> with C<OpenCL::IMAGE_DEPTH> and returns the result.
1462 1702
1463=for gengetinfo end image 1703=for gengetinfo end image
1464 1704
1465=for gengetinfo begin gl_texture 1705=for gengetinfo begin gl_texture
1466 1706
1467=item $GLenum = $gl_texture->target 1707=item $GLenum = $gl_texture->target
1468 1708
1469Calls C<clGetGLTextureInfo> with C<CL_GL_TEXTURE_TARGET> and returns the result. 1709Calls C<clGetGLTextureInfo> with C<OpenCL::GL_TEXTURE_TARGET> and returns the result.
1470 1710
1471=item $GLint = $gl_texture->gl_mipmap_level 1711=item $GLint = $gl_texture->gl_mipmap_level
1472 1712
1473Calls C<clGetGLTextureInfo> with C<CL_GL_MIPMAP_LEVEL> and returns the result. 1713Calls C<clGetGLTextureInfo> with C<OpenCL::GL_MIPMAP_LEVEL> and returns the result.
1474 1714
1475=for gengetinfo end gl_texture 1715=for gengetinfo end gl_texture
1476 1716
1477=back 1717=back
1478 1718
… …
1488 1728
1489=for gengetinfo begin sampler 1729=for gengetinfo begin sampler
1490 1730
1491=item $uint = $sampler->reference_count 1731=item $uint = $sampler->reference_count
1492 1732
1493Calls C<clGetSamplerInfo> with C<CL_SAMPLER_REFERENCE_COUNT> and returns the result. 1733Calls C<clGetSamplerInfo> with C<OpenCL::SAMPLER_REFERENCE_COUNT> and returns the result.
1494 1734
1495=item $ctx = $sampler->context 1735=item $ctx = $sampler->context
1496 1736
1497Calls C<clGetSamplerInfo> with C<CL_SAMPLER_CONTEXT> and returns the result. 1737Calls C<clGetSamplerInfo> with C<OpenCL::SAMPLER_CONTEXT> and returns the result.
1498 1738
1499=item $addressing_mode = $sampler->normalized_coords 1739=item $addressing_mode = $sampler->normalized_coords
1500 1740
1501Calls C<clGetSamplerInfo> with C<CL_SAMPLER_NORMALIZED_COORDS> and returns the result. 1741Calls C<clGetSamplerInfo> with C<OpenCL::SAMPLER_NORMALIZED_COORDS> and returns the result.
1502 1742
1503=item $filter_mode = $sampler->addressing_mode 1743=item $filter_mode = $sampler->addressing_mode
1504 1744
1505Calls C<clGetSamplerInfo> with C<CL_SAMPLER_ADDRESSING_MODE> and returns the result. 1745Calls C<clGetSamplerInfo> with C<OpenCL::SAMPLER_ADDRESSING_MODE> and returns the result.
1506 1746
1507=item $boolean = $sampler->filter_mode 1747=item $boolean = $sampler->filter_mode
1508 1748
1509Calls C<clGetSamplerInfo> with C<CL_SAMPLER_FILTER_MODE> and returns the result. 1749Calls C<clGetSamplerInfo> with C<OpenCL::SAMPLER_FILTER_MODE> and returns the result.
1510 1750
1511=for gengetinfo end sampler 1751=for gengetinfo end sampler
1512 1752
1513=back 1753=back
1514 1754
… …
1524If a callback is specified, then it will be called when compilation is 1764If a callback is specified, then it will be called when compilation is
1525finished. Note that many OpenCL implementations block your program while 1765finished. Note that many OpenCL implementations block your program while
1526compiling whether you use a callback or not. See C<build_async> if you 1766compiling whether you use a callback or not. See C<build_async> if you
1527want to make sure the build is done in the background. 1767want to make sure the build is done in the background.
1528 1768
1529Note that some OpenCL implementations atc up badly, and don't call the 1769Note that some OpenCL implementations act up badly, and don't call the
1530callback in some error cases (but call it in others). This implementation 1770callback in some error cases (but call it in others). This implementation
1531assumes the callback will always be called, and leaks memory if this is 1771assumes the callback will always be called, and leaks memory if this is
1532not so. So best make sure you don't pass in invalid values. 1772not so. So best make sure you don't pass in invalid values.
1533 1773
1774Some implementations fail with C<OpenCL::INVALID_BINARY> when the
1775compilation state is successful but some later stage fails.
1776
1777options: C<-D name>, C<-D name=definition>, C<-I dir>,
1778C<-cl-single-precision-constant>, C<-cl-denorms-are-zero>,
1779C<-cl-fp32-correctly-rounded-divide-sqrt>, C<-cl-opt-disable>,
1780C<-cl-mad-enable>, C<-cl-no-signed-zeros>, C<-cl-unsafe-math-optimizations>,
1781C<-cl-finite-math-only>, C<-cl-fast-relaxed-math>,
1782C<-w>, C<-Werror>, C<-cl-std=CL1.1/CL1.2>, C<-cl-kernel-arg-info>,
1783C<-create-library>, C<-enable-link-options>.
1784
1785build_status: OpenCL::BUILD_SUCCESS, OpenCL::BUILD_NONE,
1786OpenCL::BUILD_ERROR, OpenCL::BUILD_IN_PROGRESS.
1787
1534L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clBuildProgram.html> 1788L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clBuildProgram.html>
1535 1789
1536=item $program->build_async (\@devices = undef, $options = "", $cb->($program) = undef) 1790=item $program->build_async (\@devices = undef, $options = "", $cb->($program) = undef)
1537 1791
1538Similar to C<< ->build >>, except it starts a thread, and never fails (you 1792Similar to C<< ->build >>, except it starts a thread, and never fails (you
1539need to check the compilation status form the callback, or by polling). 1793need to check the compilation status form the callback, or by polling).
1540 1794
1795=item $program->compile (\@devices = undef, $options = "", \%headers = undef, $cb->($program) = undef)
1796
1797Compiles the given program for the given devices (or all devices if
1798undef). If C<$headers> is given, it must be a hashref with include name =>
1799OpenCL::Program pairs.
1800
1801L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clCompileProgram.html>
1802
1541=item $packed_value = $program->build_info ($device, $name) 1803=item $packed_value = $program->build_info ($device, $name)
1542 1804
1543Similar to C<< $platform->info >>, but returns build info for a previous 1805Similar to C<< $platform->info >>, but returns build info for a previous
1544build attempt for the given device. 1806build attempt for the given device.
1545 1807
… …
1560 1822
1561=for gengetinfo begin program_build 1823=for gengetinfo begin program_build
1562 1824
1563=item $build_status = $program->build_status ($device) 1825=item $build_status = $program->build_status ($device)
1564 1826
1565Calls C<clGetProgramBuildInfo> with C<CL_PROGRAM_BUILD_STATUS> and returns the result. 1827Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_STATUS> and returns the result.
1566 1828
1567=item $string = $program->build_options ($device) 1829=item $string = $program->build_options ($device)
1568 1830
1569Calls C<clGetProgramBuildInfo> with C<CL_PROGRAM_BUILD_OPTIONS> and returns the result. 1831Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_OPTIONS> and returns the result.
1570 1832
1571=item $string = $program->build_log ($device) 1833=item $string = $program->build_log ($device)
1572 1834
1573Calls C<clGetProgramBuildInfo> with C<CL_PROGRAM_BUILD_LOG> and returns the result. 1835Calls C<clGetProgramBuildInfo> with C<OpenCL::PROGRAM_BUILD_LOG> and returns the result.
1574 1836
1575=for gengetinfo end program_build 1837=for gengetinfo end program_build
1576 1838
1577=item $packed_value = $program->info ($name) 1839=item $packed_value = $program->info ($name)
1578 1840
… …
1582 1844
1583=for gengetinfo begin program 1845=for gengetinfo begin program
1584 1846
1585=item $uint = $program->reference_count 1847=item $uint = $program->reference_count
1586 1848
1587Calls C<clGetProgramInfo> with C<CL_PROGRAM_REFERENCE_COUNT> and returns the result. 1849Calls C<clGetProgramInfo> with C<OpenCL::PROGRAM_REFERENCE_COUNT> and returns the result.
1588 1850
1589=item $ctx = $program->context 1851=item $ctx = $program->context
1590 1852
1591Calls C<clGetProgramInfo> with C<CL_PROGRAM_CONTEXT> and returns the result. 1853Calls C<clGetProgramInfo> with C<OpenCL::PROGRAM_CONTEXT> and returns the result.
1592 1854
1593=item $uint = $program->num_devices 1855=item $uint = $program->num_devices
1594 1856
1595Calls C<clGetProgramInfo> with C<CL_PROGRAM_NUM_DEVICES> and returns the result. 1857Calls C<clGetProgramInfo> with C<OpenCL::PROGRAM_NUM_DEVICES> and returns the result.
1596 1858
1597=item @devices = $program->devices 1859=item @devices = $program->devices
1598 1860
1599Calls C<clGetProgramInfo> with C<CL_PROGRAM_DEVICES> and returns the result. 1861Calls C<clGetProgramInfo> with C<OpenCL::PROGRAM_DEVICES> and returns the result.
1600 1862
1601=item $string = $program->source 1863=item $string = $program->source
1602 1864
1603Calls C<clGetProgramInfo> with C<CL_PROGRAM_SOURCE> and returns the result. 1865Calls C<clGetProgramInfo> with C<OpenCL::PROGRAM_SOURCE> and returns the result.
1604 1866
1605=item @ints = $program->binary_sizes 1867=item @ints = $program->binary_sizes
1606 1868
1607Calls C<clGetProgramInfo> with C<CL_PROGRAM_BINARY_SIZES> and returns the result. 1869Calls C<clGetProgramInfo> with C<OpenCL::PROGRAM_BINARY_SIZES> and returns the result.
1608 1870
1609=for gengetinfo end program 1871=for gengetinfo end program
1610 1872
1611=item @blobs = $program->binaries 1873=item @blobs = $program->binaries
1612 1874
… …
1633 1895
1634=for gengetinfo begin kernel 1896=for gengetinfo begin kernel
1635 1897
1636=item $string = $kernel->function_name 1898=item $string = $kernel->function_name
1637 1899
1638Calls C<clGetKernelInfo> with C<CL_KERNEL_FUNCTION_NAME> and returns the result. 1900Calls C<clGetKernelInfo> with C<OpenCL::KERNEL_FUNCTION_NAME> and returns the result.
1639 1901
1640=item $uint = $kernel->num_args 1902=item $uint = $kernel->num_args
1641 1903
1642Calls C<clGetKernelInfo> with C<CL_KERNEL_NUM_ARGS> and returns the result. 1904Calls C<clGetKernelInfo> with C<OpenCL::KERNEL_NUM_ARGS> and returns the result.
1643 1905
1644=item $uint = $kernel->reference_count 1906=item $uint = $kernel->reference_count
1645 1907
1646Calls C<clGetKernelInfo> with C<CL_KERNEL_REFERENCE_COUNT> and returns the result. 1908Calls C<clGetKernelInfo> with C<OpenCL::KERNEL_REFERENCE_COUNT> and returns the result.
1647 1909
1648=item $ctx = $kernel->context 1910=item $ctx = $kernel->context
1649 1911
1650Calls C<clGetKernelInfo> with C<CL_KERNEL_CONTEXT> and returns the result. 1912Calls C<clGetKernelInfo> with C<OpenCL::KERNEL_CONTEXT> and returns the result.
1651 1913
1652=item $program = $kernel->program 1914=item $program = $kernel->program
1653 1915
1654Calls C<clGetKernelInfo> with C<CL_KERNEL_PROGRAM> and returns the result. 1916Calls C<clGetKernelInfo> with C<OpenCL::KERNEL_PROGRAM> and returns the result.
1655 1917
1656=for gengetinfo end kernel 1918=for gengetinfo end kernel
1657 1919
1658=item $packed_value = $kernel->work_group_info ($device, $name) 1920=item $packed_value = $kernel->work_group_info ($device, $name)
1659 1921
1660See C<< $platform->info >> for details. 1922See C<< $platform->info >> for details.
1661 1923
1662The reason this method is not called C<info> is that there already is an
1663C<< ->info >> method.
1664
1665L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelWorkGroupInfo.html> 1924L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetKernelWorkGroupInfo.html>
1666 1925
1667=for gengetinfo begin kernel_work_group 1926=for gengetinfo begin kernel_work_group
1668 1927
1669=item $int = $kernel->work_group_size ($device) 1928=item $int = $kernel->work_group_size ($device)
1670 1929
1671Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_WORK_GROUP_SIZE> and returns the result. 1930Calls C<clGetKernelWorkGroupInfo> with C<OpenCL::KERNEL_WORK_GROUP_SIZE> and returns the result.
1672 1931
1673=item @ints = $kernel->compile_work_group_size ($device) 1932=item @ints = $kernel->compile_work_group_size ($device)
1674 1933
1675Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_COMPILE_WORK_GROUP_SIZE> and returns the result. 1934Calls C<clGetKernelWorkGroupInfo> with C<OpenCL::KERNEL_COMPILE_WORK_GROUP_SIZE> and returns the result.
1676 1935
1677=item $ulong = $kernel->local_mem_size ($device) 1936=item $ulong = $kernel->local_mem_size ($device)
1678 1937
1679Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_LOCAL_MEM_SIZE> and returns the result. 1938Calls C<clGetKernelWorkGroupInfo> with C<OpenCL::KERNEL_LOCAL_MEM_SIZE> and returns the result.
1680 1939
1681=item $int = $kernel->preferred_work_group_size_multiple ($device) 1940=item $int = $kernel->preferred_work_group_size_multiple ($device)
1682 1941
1683Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE> and returns the result. 1942Calls C<clGetKernelWorkGroupInfo> with C<OpenCL::KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE> and returns the result.
1684 1943
1685=item $ulong = $kernel->private_mem_size ($device) 1944=item $ulong = $kernel->private_mem_size ($device)
1686 1945
1687Calls C<clGetKernelWorkGroupInfo> with C<CL_KERNEL_PRIVATE_MEM_SIZE> and returns the result. 1946Calls C<clGetKernelWorkGroupInfo> with C<OpenCL::KERNEL_PRIVATE_MEM_SIZE> and returns the result.
1688 1947
1689=for gengetinfo end kernel_work_group 1948=for gengetinfo end kernel_work_group
1949
1950=item $packed_value = $kernel->arg_info ($idx, $name)
1951
1952See C<< $platform->info >> for details.
1953
1954L<http://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/clGetKernelArgInfo.html>
1955
1956=for gengetinfo begin kernel_arg
1957
1958=item $kernel_arg_address_qualifier = $kernel->arg_address_qualifier ($idx)
1959
1960Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_ADDRESS_QUALIFIER> and returns the result.
1961
1962=item $kernel_arg_access_qualifier = $kernel->arg_access_qualifier ($idx)
1963
1964Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_ACCESS_QUALIFIER> and returns the result.
1965
1966=item $string = $kernel->arg_type_name ($idx)
1967
1968Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_TYPE_NAME> and returns the result.
1969
1970=item $kernel_arg_type_qualifier = $kernel->arg_type_qualifier ($idx)
1971
1972Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_TYPE_QUALIFIER> and returns the result.
1973
1974=item $string = $kernel->arg_name ($idx)
1975
1976Calls C<clGetKernelArgInfo> with C<OpenCL::KERNEL_ARG_NAME> and returns the result.
1977
1978=for gengetinfo end kernel_arg
1979
1980=item $kernel->setf ($format, ...)
1981
1982Sets the arguments of a kernel. Since OpenCL 1.1 doesn't have a generic
1983way to set arguments (and with OpenCL 1.2 it might be rather slow), you
1984need to specify a format argument, much as with C<printf>, to tell OpenCL
1985what type of argument it is.
1986
1987The format arguments are single letters:
1988
1989 c char
1990 C unsigned char
1991 s short
1992 S unsigned short
1993 i int
1994 I unsigned int
1995 l long
1996 L unsigned long
1997
1998 h half float (0..65535)
1999 f float
2000 d double
2001
2002 z local (octet size)
2003
2004 m memory object (buffer or image)
2005 a sampler
2006 e event
2007
2008Space characters in the format string are ignored.
2009
2010Example: set the arguments for a kernel that expects an int, two floats, a buffer and an image.
2011
2012 $kernel->setf ("i ff mm", 5, 0.5, 3, $buffer, $image);
1690 2013
1691=item $kernel->set_TYPE ($index, $value) 2014=item $kernel->set_TYPE ($index, $value)
1692 2015
1693=item $kernel->set_char ($index, $value) 2016=item $kernel->set_char ($index, $value)
1694 2017
… …
1772 2095
1773=for gengetinfo begin event 2096=for gengetinfo begin event
1774 2097
1775=item $queue = $event->command_queue 2098=item $queue = $event->command_queue
1776 2099
1777Calls C<clGetEventInfo> with C<CL_EVENT_COMMAND_QUEUE> and returns the result. 2100Calls C<clGetEventInfo> with C<OpenCL::EVENT_COMMAND_QUEUE> and returns the result.
1778 2101
1779=item $command_type = $event->command_type 2102=item $command_type = $event->command_type
1780 2103
1781Calls C<clGetEventInfo> with C<CL_EVENT_COMMAND_TYPE> and returns the result. 2104Calls C<clGetEventInfo> with C<OpenCL::EVENT_COMMAND_TYPE> and returns the result.
1782 2105
1783=item $uint = $event->reference_count 2106=item $uint = $event->reference_count
1784 2107
1785Calls C<clGetEventInfo> with C<CL_EVENT_REFERENCE_COUNT> and returns the result. 2108Calls C<clGetEventInfo> with C<OpenCL::EVENT_REFERENCE_COUNT> and returns the result.
1786 2109
1787=item $uint = $event->command_execution_status 2110=item $uint = $event->command_execution_status
1788 2111
1789Calls C<clGetEventInfo> with C<CL_EVENT_COMMAND_EXECUTION_STATUS> and returns the result. 2112Calls C<clGetEventInfo> with C<OpenCL::EVENT_COMMAND_EXECUTION_STATUS> and returns the result.
1790 2113
1791=item $ctx = $event->context 2114=item $ctx = $event->context
1792 2115
1793Calls C<clGetEventInfo> with C<CL_EVENT_CONTEXT> and returns the result. 2116Calls C<clGetEventInfo> with C<OpenCL::EVENT_CONTEXT> and returns the result.
1794 2117
1795=for gengetinfo end event 2118=for gengetinfo end event
1796 2119
1797=item $packed_value = $ev->profiling_info ($name) 2120=item $packed_value = $ev->profiling_info ($name)
1798 2121
… …
1805 2128
1806=for gengetinfo begin profiling 2129=for gengetinfo begin profiling
1807 2130
1808=item $ulong = $event->profiling_command_queued 2131=item $ulong = $event->profiling_command_queued
1809 2132
1810Calls C<clGetEventProfilingInfo> with C<CL_PROFILING_COMMAND_QUEUED> and returns the result. 2133Calls C<clGetEventProfilingInfo> with C<OpenCL::PROFILING_COMMAND_QUEUED> and returns the result.
1811 2134
1812=item $ulong = $event->profiling_command_submit 2135=item $ulong = $event->profiling_command_submit
1813 2136
1814Calls C<clGetEventProfilingInfo> with C<CL_PROFILING_COMMAND_SUBMIT> and returns the result. 2137Calls C<clGetEventProfilingInfo> with C<OpenCL::PROFILING_COMMAND_SUBMIT> and returns the result.
1815 2138
1816=item $ulong = $event->profiling_command_start 2139=item $ulong = $event->profiling_command_start
1817 2140
1818Calls C<clGetEventProfilingInfo> with C<CL_PROFILING_COMMAND_START> and returns the result. 2141Calls C<clGetEventProfilingInfo> with C<OpenCL::PROFILING_COMMAND_START> and returns the result.
1819 2142
1820=item $ulong = $event->profiling_command_end 2143=item $ulong = $event->profiling_command_end
1821 2144
1822Calls C<clGetEventProfilingInfo> with C<CL_PROFILING_COMMAND_END> and returns the result. 2145Calls C<clGetEventProfilingInfo> with C<OpenCL::PROFILING_COMMAND_END> and returns the result.
1823 2146
1824=for gengetinfo end profiling 2147=for gengetinfo end profiling
1825 2148
1826=back 2149=back
1827 2150
… …
1834=item $ev->set_status ($execution_status) 2157=item $ev->set_status ($execution_status)
1835 2158
1836Sets the execution status of the user event. Can only be called once, 2159Sets the execution status of the user event. Can only be called once,
1837either with OpenCL::COMPLETE or a negative number as status. 2160either with OpenCL::COMPLETE or a negative number as status.
1838 2161
2162execution_status: OpenCL::COMPLETE or a negative integer.
2163
1839L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetUserEventStatus.html> 2164L<http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clSetUserEventStatus.html>
1840 2165
1841=back 2166=back
2167
2168=head2 THE OpenCL::Mapped CLASS
2169
2170This class represents objects mapped into host memory. They are
2171represented by a blessed string scalar. The string data is the mapped
2172memory area, that is, if you read or write it, then the mapped object is
2173accessed directly.
2174
2175You must only ever use operations that modify the string in-place - for
2176example, a C<substr> that doesn't change the length, or maybe a regex that
2177doesn't change the length. Any other operation might cause the data to be
2178copied.
2179
2180When the object is destroyed it will enqueue an implicit unmap operation
2181on the queue that was used to create it.
2182
2183Keep in mind that you I<need> to unmap (or destroy) mapped objects before
2184OpenCL sees the changes, even if some implementations don't need this
2185sometimes.
2186
2187Example, replace the first two floats in the mapped buffer by 1 and 2.
2188
2189 my $mapped = $queue->map_buffer ($buf, ...
2190 $mapped->event->wait; # make sure it's there
2191
2192 # now replace first 8 bytes by new data, which is exactly 8 bytes long
2193 # we blindly assume device endianness to equal host endianness
2194 # (and of course, we assume iee 754 single precision floats :)
2195 substr $$mapped, 0, 8, pack "f*", 1, 2;
2196
2197=over 4
2198
2199=item $ev = $mapped->unmap ($wait_events...)
2200
2201Unmaps the mapped memory object, using the queue originally used to create
2202it, quite similarly to C<< $queue->unmap ($mapped, ...) >>.
2203
2204=item $bool = $mapped->mapped
2205
2206Returns whether the object is still mapped - true before an C<unmap> is
2207enqueued, false afterwards.
2208
2209=item $ev = $mapped->event
2210
2211Return the event object associated with the mapped object. Initially, this
2212will be the event object created when mapping the object, and after an
2213unmap, this will be the event object that the unmap operation created.
2214
2215=item $mapped->wait
2216
2217Same as C<< $mapped->event->wait >> - makes sure no operations on this
2218mapped object are outstanding.
2219
2220=item $bytes = $mapped->size
2221
2222Returns the size of the mapped area, in bytes. Same as C<length $$mapped>.
2223
2224=item $ptr = $mapped->ptr
2225
2226Returns the raw memory address of the mapped area.
2227
2228=item $mapped->set ($offset, $data)
2229
2230Replaces the data at the given C<$offset> in the memory area by the new
2231C<$data>. This method is safer than direct manipulation of C<$mapped>
2232because it does bounds-checking, but also slower.
2233
2234=item $data = $mapped->get ($offset, $length)
2235
2236Returns (without copying) a scalar representing the data at the given
2237C<$offset> and C<$length> in the mapped memory area. This is the same as
2238the following substr, except much slower;
2239
2240 $data = substr $$mapped, $offset, $length
2241
2242=cut
2243
2244sub OpenCL::Mapped::get {
2245 substr ${$_[0]}, $_[1], $_[2]
2246}
2247
2248=back
2249
2250=head2 THE OpenCL::MappedBuffer CLASS
2251
2252This is a subclass of OpenCL::Mapped, representing mapped buffers.
2253
2254=head2 THE OpenCL::MappedImage CLASS
2255
2256This is a subclass of OpenCL::Mapped, representing mapped images.
2257
2258=over 4
2259
2260=item $bytes = $mapped->row_pitch
2261
2262=item $bytes = $mapped->slice_pitch
2263
2264Return the row or slice pitch of the image that has been mapped.
2265
2266=back
2267
1842 2268
1843=cut 2269=cut
1844 2270
18451; 22711;
1846 2272

Diff Legend

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