--- OpenCL/OpenCL.pm 2012/05/05 12:54:03 1.77 +++ OpenCL/OpenCL.pm 2012/05/07 01:00:31 1.86 @@ -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. @@ -99,37 +99,6 @@ Enqueue buffer reads for your output buffer to read results. -=head1 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 cna 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. - =head1 EXAMPLES =head2 Enumerate all devices and get contexts for them. @@ -246,8 +215,8 @@ =head2 Use the OpenGL module to share a texture between OpenCL and OpenGL and draw some julia set flight effect. -This is quite a long example to get you going - you can download it from -L. +This is quite a long example to get you going - you can also download it +from L. use OpenGL ":all"; use OpenCL; @@ -421,12 +390,55 @@ 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<0> (in +some cases, this will make them indistinguishable from real constants, +sorry). + +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 @@ -587,7 +599,7 @@ our $POLL_FUNC; # set by XS BEGIN { - our $VERSION = '0.99'; + our $VERSION = '1.0'; require XSLoader; XSLoader::load (__PACKAGE__, $VERSION); @@ -633,9 +645,12 @@ =item $str = OpenCL::err2str [$errval] -Converts an error value into a human readable string. IF no error value is +Converts an error value into a human readable string. If no error value is given, then the last error will be used (as returned by OpenCL::errno). +The latest version of this module knows the error constants +listed in L. + =item $str = OpenCL::enum2str $enum Converts most enum values (of parameter names, image format constants, @@ -644,6 +659,9 @@ very helpful to pass it through this function to maybe get some readable string out of it. +The latest version of this module knows the enumaration constants +listed in L. + =item @platforms = OpenCL::platforms Returns all available OpenCL::Platform objects. @@ -754,7 +772,7 @@ =item $ctx = $platform->context ($properties, \@devices, $callback->($err, $pvt) = $print_stderr) Create a new OpenCL::Context object using the given device object(s)- a -CL_CONTEXT_PLATFORM property is supplied automatically. +OpenCL::CONTEXT_PLATFORM property is supplied automatically. L @@ -810,6 +828,32 @@ See C<< $platform->info >> for details. +type: OpenCL::DEVICE_TYPE_DEFAULT, OpenCL::DEVICE_TYPE_CPU, +OpenCL::DEVICE_TYPE_GPU, OpenCL::DEVICE_TYPE_ACCELERATOR, +OpenCL::DEVICE_TYPE_CUSTOM, OpenCL::DEVICE_TYPE_ALL. + +fp_config: OpenCL::FP_DENORM, OpenCL::FP_INF_NAN, OpenCL::FP_ROUND_TO_NEAREST, +OpenCL::FP_ROUND_TO_ZERO, OpenCL::FP_ROUND_TO_INF, OpenCL::FP_FMA, +OpenCL::FP_SOFT_FLOAT, OpenCL::FP_CORRECTLY_ROUNDED_DIVIDE_SQRT. + +mem_cache_type: OpenCL::NONE, OpenCL::READ_ONLY_CACHE, OpenCL::READ_WRITE_CACHE. + +local_mem_type: OpenCL::LOCAL, OpenCL::GLOBAL. + +exec_capabilities: OpenCL::EXEC_KERNEL, OpenCL::EXEC_NATIVE_KERNEL. + +command_queue_properties: OpenCL::QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE, +OpenCL::QUEUE_PROFILING_ENABLE. + +partition_properties: OpenCL::DEVICE_PARTITION_EQUALLY, +OpenCL::DEVICE_PARTITION_BY_COUNTS, OpenCL::DEVICE_PARTITION_BY_COUNTS_LIST_END, +OpenCL::DEVICE_PARTITION_BY_AFFINITY_DOMAIN. + +affinity_domain: OpenCL::DEVICE_AFFINITY_DOMAIN_NUMA, +OpenCL::DEVICE_AFFINITY_DOMAIN_L4_CACHE, OpenCL::DEVICE_AFFINITY_DOMAIN_L3_CACHE, +OpenCL::DEVICE_AFFINITY_DOMAIN_L2_CACHE, OpenCL::DEVICE_AFFINITY_DOMAIN_L1_CACHE, +OpenCL::DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE. + L =item @devices = $device->sub_devices (\@properties) @@ -1198,7 +1242,6 @@ OpenCL::SIGNED_INT32, OpenCL::UNSIGNED_INT8, OpenCL::UNSIGNED_INT16, OpenCL::UNSIGNED_INT32, OpenCL::HALF_FLOAT, OpenCL::FLOAT. - type: OpenCL::MEM_OBJECT_BUFFER, OpenCL::MEM_OBJECT_IMAGE2D, OpenCL::MEM_OBJECT_IMAGE3D, OpenCL::MEM_OBJECT_IMAGE2D_ARRAY, OpenCL::MEM_OBJECT_IMAGE1D, OpenCL::MEM_OBJECT_IMAGE1D_ARRAY, @@ -1383,11 +1426,11 @@ L -=item $ev = $queue->read_buffer_rect (OpenCL::Memory buf, cl_bool blocking, $buf_x, $buf_y, $buf_z, $host_x, $host_y, $host_z, $width, $height, $depth, $buf_row_pitch, $buf_slice_pitch, $host_row_pitch, $host_slice_pitch, $data, $wait_events...) +$eue->read_buffer_rect ($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...) http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueReadBufferRect.html -=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...) +=item $ev = $queue->write_buffer_rect ($buf, $blocking, $buf_y, $host_x, $host_z, $height, $buf_row_pitch, $host_row_pitch, $data, $wait_events...) http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clEnqueueWriteBufferRect.html @@ -1581,8 +1624,8 @@ my $mapped = $queue->map_image ($image, 1, OpenCL::MAP_WRITE); - $mapped->set ($_ * $mapped->row_pitch, pack "C", 5) - for 0..$image->height; + $mapped->write ($_ * $mapped->row_pitch, pack "C", 5) + for 0 .. $mapped->height - 1; $mapped->unmap;. $mapped->wait; # only needed for out of order queues normally @@ -1612,6 +1655,12 @@ L +=item $memory->destructor_callback ($cb->()) + +Sets a callback that will be invoked after the memory object is destructed. + +L + =for gengetinfo begin mem =item $mem_object_type = $mem->type @@ -1678,7 +1727,7 @@ =item $subbuf = $buf_obj->sub_buffer_region ($flags, $origin, $size) Creates an OpenCL::Buffer objects from this buffer and returns it. The -C is assumed to be C. +C is assumed to be C. L @@ -1704,7 +1753,7 @@ =item ($channel_order, $channel_data_type) = $image->format Returns the channel order and type used to create the image by calling -C with C. +C with C. =for gengetinfo begin image @@ -1837,6 +1886,11 @@ Similar to C<< $platform->info >>, but returns build info for a previous build attempt for the given device. +binary_type: OpenCL::PROGRAM_BINARY_TYPE_NONE, +OpenCL::PROGRAM_BINARY_TYPE_COMPILED_OBJECT, +OpenCL::PROGRAM_BINARY_TYPE_LIBRARY, +OpenCL::PROGRAM_BINARY_TYPE_EXECUTABLE. + L =item $kernel = $program->kernel ($function_name) @@ -1866,6 +1920,10 @@ Calls C with C and returns the result. +=item $binary_type = $program->binary_type ($device) + +Calls C with C and returns the result. + =for gengetinfo end program_build =item $packed_value = $program->info ($name) @@ -2289,14 +2347,38 @@ =over 4 +=item $pixels = $mapped->width + +=item $pixels = $mapped->height + +=item $pixels = $mapped->depth + +Return the width/height/depth of the mapped image region, in pixels. + =item $bytes = $mapped->row_pitch =item $bytes = $mapped->slice_pitch Return the row or slice pitch of the image that has been mapped. -=back +=item $bytes = $mapped->element_size + +Return the size of a single pixel. + +=item $data = $mapped->get_row ($count, $x=0, $y=0, $z=0) +Return C<$count> pixels from the given coordinates. The pixel data must +be completely contained within a single row. + +If C<$count> is C, then all the remaining pixels in that row are +returned. + +=item $mapped->set_row ($data, $x=0, $y=0, $z=0) + +Write the given pixel data at the given coordinate. The pixel data must +be completely contained within a single row. + +=back =cut