Module ocl::core
[−]
[src]
Thin wrappers for the OpenCL FFI functions and types.
The layer between the hard rough and the soft furry 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. The 'core' and 'standard' interfaces are all completely interoperable, and generally feature-equivalent.
Even Lower Level: cl_h
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 (core::PlatformId,
core::Context, etc.) and passed to core
module functions. 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 identical or virtually identical (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 100% comprehensively evaluated and tested. Please file an issue if you discover something!
Length vs Size
No, not that...
Quantifiers passed to functions in the OpenCL API are generally expressed
in terms of bytes where units passed to functions in this module are
expected to be bytes / sizeof(T)
, corresponding with units returned by
the ubiquitous .len()
method. The suffix '_size' or '_bytes' is
generally used when a parameter deviates from this convention.
More Documentation
As most of the functions here are minimally documented, please refer to
the official OpenCL documentation linked below. Although there isn't a
precise 1:1 parameter mapping between the core
and original functions,
it's close enough (modulo the size/len difference discussed above) 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/functions.rs
for
more 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.
[STATUS]:
Coverage of core stuff: 100%.
Coverage of peripheral
stuff: 90%.
core
Stands Alone
This module may eventually be moved to its own separate crate (with its
dependencies cl_h
and error
).
Structs
BufferRegion |
Defines a buffer region for creating a sub-buffer. |
CommandQueue |
cl_command_queue |
CommandQueueProperties |
cl_command_queue_properties - bitfield |
Context |
cl_context |
ContextProperties |
Context properties list. |
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 |
List of |
EventRefWrapper |
Wrapper used by |
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] 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. |
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
ClDeviceIdPtr |
Types with a reference to a raw device_id pointer. |
ClEventPtrNew |
Types with a mutable pointer to a new, null raw event pointer. |
ClEventRef |
Types with a reference to a raw event pointer. |
ClPlatformIdPtr |
Types with a reference to a raw platform_id pointer. |
OclPrm |
[POSSIBLY INCOMPLETE] A number compatible with OpenCL. |
Functions
build_program |
Builds a program. |
compile_program |
[UNIMPLEMENTED] |
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 |
Returns a new context pointer valid for all devices in |
create_context_from_type |
[UNIMPLEMENTED] |
create_image |
Returns a new image (mem) pointer. |
create_kernel |
Returns a new kernel pointer. |
create_kernels_in_program |
[UNIMPLEMENTED] |
create_program_with_binary |
[UNTESTED] Creates a program object for a context, and loads the binary bits specified by binary into the program object. |
create_program_with_built_in_kernels |
[UNIMPLEMENTED] |
create_program_with_source |
Creates a new program. |
create_sampler |
Creates and returns a new sampler object. |
create_sub_buffer |
[UNTESTED] Creates a new buffer object (referred to as a sub-buffer object) from an existing buffer object. |
create_sub_devices |
[UNIMPLEMENTED] |
create_user_event |
[UNTESTED] Creates an event not already associated with any command. |
default_device_type |
Returns the default device type bitflags as specified by environment
variable or |
default_platform |
Returns the default or first platform. |
default_platform_idx |
Returns the default platform if set by an environment variable or config file. |
enqueue_barrier_with_wait_list |
[UNTESTED] A synchronization point that enqueues a barrier operation. |
enqueue_copy_buffer |
[UNTESTED] Copies the contents of one buffer to another. |
enqueue_copy_buffer_rect |
Enqueues a command to copy a rectangular region from a buffer object to another buffer object. |
enqueue_copy_buffer_to_image |
[UNTESTED] Enqueues a command to copy a buffer object to an image object. |
enqueue_copy_image |
Enqueues a command to copy image objects. |
enqueue_copy_image_to_buffer |
[UNTESTED] Enqueues a command to copy an image object to a buffer object. |
enqueue_fill_buffer |
Enqueues a command to fill a buffer object with a pattern of a given pattern size. |
enqueue_fill_image |
[UNTESTED] Enqueues a command to fill an image object with a specified color. |
enqueue_kernel |
Enqueues a command to execute a kernel on a device. |
enqueue_map_buffer |
[UNTESTED]
Enqueues a command to map a region of the buffer object given
by |
enqueue_map_image |
[UNTESTED]
Enqueues a command to map a region of the image object given by |
enqueue_marker_with_wait_list |
[UNTESTED] Enqueues a marker command which waits for either a list of events to complete, or all previously enqueued commands to complete. |
enqueue_migrate_mem_objects |
[UNTESTED] Enqueues a command to indicate which device a set of memory objects should be associated with. |
enqueue_native_kernel |
[UNIMPLEMENTED] |
enqueue_read_buffer |
Enqueues a read from device memory referred to by |
enqueue_read_buffer_rect |
Enqueues a command to read from a rectangular region from a buffer object to host memory. |
enqueue_read_image |
Reads an image from device to host memory. |
enqueue_task |
[UNTESTED] Enqueues a command to execute a kernel on a device. |
enqueue_unmap_mem_object |
[UNTESTED] Enqueues a command to unmap a previously mapped region of a memory object. |
enqueue_write_buffer |
Enqueues a write from host memory, |
enqueue_write_buffer_rect |
Enqueues a command to write from a rectangular region from host memory to a buffer object. |
enqueue_write_image |
Enqueues a command to write to an image or image array object from host memory. |
finish |
Waits for a queue to finish. |
flush |
[UNTESTED] Flushes a command queue. |
get_command_queue_info |
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 |
Returns information about a device. |
get_event_info |
Get event info. |
get_event_profiling_info |
Get event profiling info (for debugging / benchmarking). |
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 |
Get image info. |
get_kernel_arg_info |
Get kernel arg info. |
get_kernel_info |
Get kernel info. |
get_kernel_work_group_info |
Get kernel work group info. |
get_mem_object_info |
Get mem object info. |
get_platform_ids |
Returns a list of available platforms as 'core' objects. |
get_platform_info |
Returns platform information of the requested type. |
get_program_build_info |
Get program build info. |
get_program_info |
Get program info. |
get_sampler_info |
Returns information about the sampler object. |
get_supported_image_formats |
Returns a list of supported image formats. |
link_program |
[UNIMPLEMENTED] |
program_build_err |
If the program pointed to by |
release_command_queue |
Decrements the reference count of a command queue. |
release_context |
Decrements reference count of a context. |
release_device |
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 |
Decrements a sampler reference counter. |
retain_command_queue |
Increments the reference count of a command queue. |
retain_context |
Increments the reference count of a context. |
retain_device |
Increments the reference count of a device. |
retain_event |
Increments an event's reference counter. |
retain_kernel |
Increments a kernel reference counter. |
retain_mem_object |
Increments the reference counter of a mem object. |
retain_program |
Increments a program reference counter. |
retain_sampler |
Increments a sampler reference counter. |
set_event_callback |
Sets a callback function which is called as soon as the |
set_kernel_arg |
Sets the argument value for a specific argument of a kernel. |
set_mem_object_destructor_callback |
[UNIMPLEMENTED] |
set_user_event_status |
[UNTESTED] Updates a user events status. |
verify_context |
Verifies that the |
wait_for_event |
Blocks until an event is complete. |
wait_for_events |
Blocks until the first |
Type Definitions
BuildProgramCallbackFn | |
CreateContextCallbackFn | |
EventCallbackFn | |
UserDataPtr |