Module ocl::core
[−]
[src]
Thin wrappers for the OpenCL FFI functions and types.
The layer between the metal and the soft fuzzy parts...
Allows access to OpenCL FFI functions with a minimal layer of abstraction, providing both safety and convenience. Using functions in this module is only recommended for use when functionality has not yet been implemented on the 'standard' ocl interfaces, although the 'core' and 'standard' interfaces are all completely interoperable (and generally feature-equivalent).
Object pointers can generally be shared between threads (except for kernel -- see the official clSetKernelArg documentation for details) [FIXME: Send impl's temporarily removed pending further evaluation].
Even Lower Level: cl_h
Not as core as...
If there's still something missing or for some reason you need direct FFI access, use the functions in the cl_h module. The pointers used by cl_h functions can be wrapped in core wrappers (PlatformIdRaw, ContextRaw, etc.) and passed to core module functions and likewise the other way around (using, for example: EventRaw::as_ptr).
Performance
Performance between all three interface layers, cl_h, core, and the 'standard' types, is virtually identical for non-trival uses (if not, please file an issue).
Safety
At the time of writing, some functions still may break Rust's usual safety promises and have not been comprehensively tested or evaluated. Please file an issue if you discover something!
Panics
[FIXME]: NEEDS UPDATE:
All functions will panic upon OpenCL error. This will be changing over time. Certain errors will eventually be returned as an Error type instead.
More Documentation
As most of the functions here are minimally documented, please refer to the
official OpenCL documentation linked below. Although there isn't an exact
1:1 parameter mapping between the core and original functions,
it's close enough to help sort out any questions you may have until a
more thorough documentation pass can be made. View the source code in
src/core/function.rs for mapping details.
OpenCL 1.2 SDK Reference: https://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/
Help Wanted
Please help complete coverage of any FFI functions you may need by filing an issue or creating a pull request.
Coverage of core stuff: 80%.
Coverage of peripheral stuff: 5% - 10%.
core Stands Alone
This module may eventually be moved to its own separate crate (with its dependencies cl_h and error).
Structs
| CommandQueue |
cl_command_queue |
| CommandQueueProperties |
cl_command_queue_properties - bitfield |
| Context |
cl_context |
| ContextProperties |
[FIXME: Minimally tested] Context properties. |
| DeviceAffinityDomain |
cl_device_affinity_domain |
| DeviceExecCapabilities |
cl_device_exec_capabilities - bitfield |
| DeviceFpConfig |
cl_device_fp_config - bitfield |
| DeviceId |
cl_device_id |
| DeviceType |
cl_device_type - bitfield |
| Event |
cl_event |
| EventList |
Reference counted list of |
| EventRefWrapper | |
| ImageDescriptor |
An image descriptor use in the creation of |
| ImageFormat |
Image format properties used by |
| Kernel |
cl_kernel |
| KernelArgTypeQualifier |
cl_kernel_arg_type_qualifer |
| MapFlags |
cl_map_flags - bitfield |
| Mem |
cl_mem |
| MemFlags |
cl_mem_flags - bitfield |
| MemMigrationFlags |
cl_mem_migration_flags - bitfield |
| PlatformId |
cl_platform_id |
| Program |
cl_program |
| ProgramBinaryType |
cl_program_binary_type |
| Sampler |
cl_sampler |
Enums
| AddressingMode |
cl_addressing_mode |
| BufferCreateType |
cl_buffer_create_type |
| BuildStatus |
cl_build_status |
| Cbool |
cl_bool |
| ChannelType |
cl_channel_type |
| CommandExecutionStatus |
command execution status |
| CommandQueueInfo |
cl_command_queue_info |
| CommandQueueInfoResult |
[UNSTABLE][INCOMPLETE] A command queue info result. |
| CommandType |
cl_command_type |
| ContextInfo |
cl_context_info |
| ContextInfoOrPropertiesPointerType |
cl_context_info + cl_context_properties |
| ContextInfoResult |
[UNSTABLE][INCOMPLETE] A context info result. |
| ContextProperty | |
| DeviceInfo |
cl_device_info |
| DeviceInfoResult |
A device info result. |
| DeviceLocalMemType |
cl_device_local_mem_type |
| DeviceMemCacheType |
cl_mem_cache_type |
| EventInfo |
cl_event_info |
| EventInfoResult |
[UNSTABLE][INCOMPLETE] An event info result. |
| FilterMode |
cl_filter_mode |
| ImageChannelDataType |
Describes the size of the channel data type. The number of bits per element determined by the image_channel_data_type and image_channel_order must be a power of two. The list of supported values is described in the table below. (from SDK) |
| ImageChannelOrder |
Specifies the number of channels and the channel layout i.e. the memory layout in which channels are stored in the image. Valid values are described in the table below. (from SDK) |
| ImageInfo |
cl_image_info |
| ImageInfoResult |
[UNSTABLE][INCOMPLETE] An image info result. |
| KernelArg |
[UNSAFE: Not thoroughly tested, Some variants dangerous] Kernel argument option type. |
| KernelArgAccessQualifier |
cl_kernel_arg_access_qualifier |
| KernelArgAddressQualifier |
cl_kernel_arg_address_qualifier |
| KernelArgInfo |
cl_kernel_arg_info |
| KernelArgInfoResult |
[UNSTABLE][INCOMPLETE] A kernel arg info result. |
| KernelInfo |
cl_kernel_info |
| KernelInfoResult |
[UNSTABLE][INCOMPLETE] A kernel info result. |
| KernelWorkGroupInfo |
cl_kernel_work_group_info |
| KernelWorkGroupInfoResult |
[UNSTABLE][INCOMPLETE] A kernel work groups info result. |
| MemInfo |
cl_mem_info |
| MemInfoResult |
[UNSTABLE][INCOMPLETE] A mem info result. |
| MemObjectType |
cl_mem_object_type |
| PartitionProperty |
cl_partition_property |
| PlatformInfo |
cl_platform_info |
| PlatformInfoResult |
Platform info result. TODO: ADD ERROR VARIANT. |
| Polling |
cl_bool: Polling |
| ProfilingInfo |
cl_profiling_info |
| ProfilingInfoResult |
[UNSTABLE][INCOMPLETE] A profiling info result. |
| ProgramBuildInfo |
cl_program_build_info |
| ProgramBuildInfoResult |
[UNSTABLE][INCOMPLETE] A program build info result. |
| ProgramInfo |
cl_program_info |
| ProgramInfoResult |
[UNSTABLE][INCOMPLETE] A program info result. |
| SamplerInfo |
cl_sampler_info |
| SamplerInfoResult |
[UNSTABLE][INCOMPLETE] A sampler info result. |
Constants
Traits
| ClEventPtrNew | |
| ClEventRef | |
| OclNum |
[POSSIBLY INCOMPLETE] A number compatible with OpenCL. |
Functions
| build_program |
Builds a program. |
| compile_program |
[UNIMPLEMENTED][PLACEHOLDER] |
| create_buffer |
Returns a new buffer pointer with size (bytes): |
| create_build_program |
Creates, builds, and returns a new program pointer from |
| create_command_queue |
Returns a new command queue pointer. |
| create_context |
[INCOMPLETE] Returns a new context pointer valid for all devices in
|
| create_context_from_type |
[UNIMPLEMENTED][PLACEHOLDER] |
| create_image |
Returns a new image (mem) pointer. |
| create_kernel |
Returns a new kernel pointer. |
| create_kernels_in_program |
[UNIMPLEMENTED][PLACEHOLDER] |
| create_program_with_binary |
[UNIMPLEMENTED][PLACEHOLDER] |
| create_program_with_built_in_kernels |
[UNIMPLEMENTED][PLACEHOLDER] |
| create_program_with_source |
Creates a new program. |
| create_sampler |
[UNTESTED] Returns a new sampler. |
| create_sub_buffer |
[UNIMPLEMENTED][PLACEHOLDER] |
| create_sub_devices |
[UNIMPLEMENTED][PLACEHOLDER] |
| create_user_event |
[UNTESTED] Creates an event not already associated with any command. |
| enqueue_barrier_with_wait_list |
[UNIMPLEMENTED][PLACEHOLDER] |
| enqueue_copy_buffer |
[UNTESTED][UNUSED] |
| enqueue_copy_buffer_rect |
[UNIMPLEMENTED][PLACEHOLDER] |
| enqueue_copy_buffer_to_image |
[UNIMPLEMENTED][PLACEHOLDER] |
| enqueue_copy_image |
[UNIMPLEMENTED][PLACEHOLDER] |
| enqueue_copy_image_to_buffer |
[UNIMPLEMENTED][PLACEHOLDER] |
| enqueue_fill_buffer |
[UNIMPLEMENTED][PLACEHOLDER] |
| enqueue_fill_image |
[UNIMPLEMENTED][PLACEHOLDER] |
| enqueue_kernel |
Enqueues a command to execute a kernel on a device. |
| enqueue_map_buffer |
[UNIMPLEMENTED][PLACEHOLDER] |
| enqueue_map_image |
[UNIMPLEMENTED][PLACEHOLDER] |
| enqueue_marker_with_wait_list |
[UNIMPLEMENTED][PLACEHOLDER] |
| enqueue_migrate_mem_objects |
[UNIMPLEMENTED][PLACEHOLDER] |
| enqueue_native_kernel |
[UNIMPLEMENTED][PLACEHOLDER] |
| enqueue_read_buffer |
Enqueues a read from device memory referred to by |
| enqueue_read_buffer_rect |
[UNIMPLEMENTED][PLACEHOLDER] Enqueue commands to read from a rectangular region from a buffer object to host memory. |
| enqueue_read_image |
[UNIMPLEMENTED][PLACEHOLDER] |
| enqueue_task |
[UNTESTED] Enqueues a command to execute a kernel on a device. |
| enqueue_unmap_mem_object |
[UNIMPLEMENTED][PLACEHOLDER] |
| enqueue_write_buffer |
Enqueues a write from host memory, |
| enqueue_write_buffer_rect |
[UNIMPLEMENTED][PLACEHOLDER] |
| enqueue_write_image |
[UNIMPLEMENTED][PLACEHOLDER] |
| finish |
Waits for a queue to finish. |
| flush |
[UNTESTED] Flushes a command queue. |
| get_command_queue_info |
[UNTESTED] Returns information about a command queue |
| get_context_info |
Returns various kinds of context information. |
| get_device_ids |
Returns a list of available devices for a particular platform. |
| get_device_info |
[INCOMPLETE][WORK IN PROGRESS] Returns information about a device. |
| get_event_info |
[UNIMPLEMENTED][PLACEHOLDER] |
| get_event_profiling_info |
[UNIMPLEMENTED][PLACEHOLDER] |
| get_event_status |
Returns the status of |
| get_extension_function_address_for_platform |
[UNTESTED]
Returns the address of the extension function named by |
| get_image_info |
[UNIMPLEMENTED][PLACEHOLDER] |
| get_kernel_arg_info |
[UNIMPLEMENTED][PLACEHOLDER] |
| get_kernel_info |
[UNIMPLEMENTED][PLACEHOLDER] |
| get_kernel_work_group_info |
[UNIMPLEMENTED][PLACEHOLDER] |
| get_max_work_group_size | |
| get_mem_object_info |
[UNIMPLEMENTED][PLACEHOLDER] |
| get_platform_ids |
Returns a list of available platforms as 'core' objects. |
| get_platform_info |
[UNTESTED] Returns platform information of the requested type. |
| get_program_build_info |
[UNIMPLEMENTED][PLACEHOLDER] |
| get_program_info |
[UNIMPLEMENTED][PLACEHOLDER] |
| get_sampler_info |
[UNIMPLEMENTED][PLACEHOLDER] |
| get_supported_image_formats |
[UNIMPLEMENTED][PLACEHOLDER] |
| link_program |
[UNIMPLEMENTED][PLACEHOLDER] |
| platform_name |
[UNTESTED] Returns the platform name. |
| program_build_err |
If the program pointed to by |
| release_command_queue |
Decrements the reference count of a command queue. |
| release_context |
[UNTESTED] Decrements reference count of a context. |
| release_device |
[UNTESTED] Decrements the reference count of a device. |
| release_event |
Decrements an event's reference counter. |
| release_kernel |
Decrements a kernel reference counter. |
| release_mem_object |
Decrements the reference counter of a mem object. |
| release_program |
Decrements a program reference counter. |
| release_sampler |
[UNTESTED] Decrements a sampler reference counter. |
| retain_command_queue |
[UNTESTED] Increments the reference count of a command queue. |
| retain_context |
[UNTESTED] Increments the reference count of a context. |
| retain_device |
[UNTESTED] Increments the reference count of a device. |
| retain_event |
[UNTESTED] Increments an event's reference counter. |
| retain_kernel |
[UNTESTED] Increments a kernel reference counter. |
| retain_mem_object |
[UNTESTED] Increments the reference counter of a mem object. |
| retain_program |
[UNTESTED] Increments a program reference counter. |
| retain_sampler |
[UNTESTED] Increments a sampler reference counter. |
| set_event_callback | |
| set_kernel_arg |
Sets the argument value for a specific argument of a kernel. |
| set_mem_object_destructor_callback |
[UNIMPLEMENTED][PLACEHOLDER] |
| set_user_event_status |
[UNIMPLEMENTED][PLACEHOLDER] |
| unload_platform_compiler |
[UNTESTED] Unloads a platform compiler. |
| verify_context |
Verifies that the |
| wait_for_event |
[FIXME]: Why are we wrapping in this array? Fix this. |
| wait_for_events |
Type Definitions
| EventCallbackFn |