# Crate ocl_core [−] [src]

Thin wrappers for the `OpenCL` FFI functions and types.

Allows access to `OpenCL` FFI functions with a minimal layer of zero-cost abstraction, providing, safety, performance, and convenience. The `ocl` crate contains higher level and easier to use interfaces to the functionality contained within.

## Even Lower Level: `cl-sys`

If there's still something missing or for some reason you need direct FFI access, use the functions in the `cl-sys` module. The pointers used by `cl-sys` functions can be wrapped in `ocl-core` wrappers (`ocl_core::PlatformId`, `ocl_core::Context`, etc.) and passed to `ocl-core` module functions. Likewise the other way around (using, for example: [`EventRaw::as_ptr`]).

## Performance

Performance between all three interface layers, `cl-sys`, `ocl-core`, and the 'standard' (`ocl`) types, is identical or virtually identical (if not, please file an issue).

## Safety

Running any kernel at all is inherently unsafe. The guarantee we aim to make in this library is that if there is a segfault or invalid memory access, the fault lies within the kernel. No effort is or will be made to verify or sanitize kernels. Consider all kernels within user-supplied programs just as if you would an `unsafe fn`.

## Length vs Size

No, not that...

Quantifiers passed to functions in the `OpenCL` API are generally expressed in bytes. Units passed to functions in this library 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.

## Version Control

The version control system is in place to ensure that you don't call functions that your hardware/driver does not support.

Functions in this crate with the `[Version Controlled: OpenCL {...}+]` tag in the description require an additional parameter, `device_version` or `device_versions`: a parsed result (or slice of results) of `DeviceInfo::Version`. This is a runtime check to ensure that the device supports the function being called. Calling a function which a particular device does not support will likely cause a segmentation fault and possibly data corruption.

Saving the `OpenclVersion` returned from `device_version()` for your device(s) at the start of your program and passing it each time you call a version controlled function is the fastest and safest method (see the `ocl` library for an example). The cost of this check is little more than a single `if` statement.

Passing `None` for `device_version` will cause an automated version check which has a small cost (calling info function, parsing the version number etc.) but is a safe option if you are not sure what to do.

Passing the result of a call to `OpenclVersion::max()` or passing a fake version will bypass any safety checks and has all of the risks described above. Only do this if you're absolutely sure you know what you're doing and are not concerned about segfaults and data integrity.

## 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/types/functions.rs` for more mapping details.

'OpenCL' 1.2 SDK Reference: https://www.khronos.org/registry/cl/sdk/1.2/docs/man/xhtml/

## Re-exports

`pub extern crate cl_sys as ffi;`
`pub use self::error::Error;`
`pub use self::error::Result;`
`pub use self::error::ErrorKind;`
`pub use self::types::abs::ClWaitListPtr;`
`pub use self::types::abs::ClNullEventPtr;`
`pub use self::types::abs::ClEventPtrRef;`
`pub use self::types::abs::ClPlatformIdPtr;`
`pub use self::types::abs::ClDeviceIdPtr;`
`pub use self::types::abs::ClContextPtr;`
`pub use self::types::abs::EventRefWrapper;`
`pub use self::types::abs::PlatformId;`
`pub use self::types::abs::DeviceId;`
`pub use self::types::abs::Context;`
`pub use self::types::abs::CommandQueue;`
`pub use self::types::abs::Mem;`
`pub use self::types::abs::Program;`
`pub use self::types::abs::Kernel;`
`pub use self::types::abs::Event;`
`pub use self::types::abs::Sampler;`
`pub use self::types::abs::ClVersions;`
`pub use self::types::abs::AsMem;`
`pub use self::types::abs::MemCmdRw;`
`pub use self::types::abs::MemCmdAll;`
`pub use self::types::abs::MemMap;`
`pub use self::types::structs;`
`pub use self::types::structs::OpenclVersion;`
`pub use self::types::structs::ContextProperties;`
`pub use self::types::structs::ImageFormatParseError;`
`pub use self::types::structs::ImageFormatParseResult;`
`pub use self::types::structs::ImageFormat;`
`pub use self::types::structs::ImageDescriptor;`
`pub use self::types::structs::BufferRegion;`
`pub use self::types::structs::ContextPropertyValue;`
`pub use self::types::structs::ArgVal;`
`pub use self::types::enums::EmptyInfoResultError;`
`pub use self::types::enums::PlatformInfoResult;`
`pub use self::types::enums::DeviceInfoResult;`
`pub use self::types::enums::ContextInfoResult;`
`pub use self::types::enums::GlContextInfoResult;`
`pub use self::types::enums::CommandQueueInfoResult;`
`pub use self::types::enums::MemInfoResult;`
`pub use self::types::enums::ImageInfoResult;`
`pub use self::types::enums::SamplerInfoResult;`
`pub use self::types::enums::ProgramInfoResult;`
`pub use self::types::enums::ProgramBuildInfoResult;`
`pub use self::types::enums::KernelInfoResult;`
`pub use self::types::enums::KernelArgInfoResult;`
`pub use self::types::enums::KernelWorkGroupInfoResult;`
`pub use self::types::enums::EventInfoResult;`
`pub use self::types::enums::ProfilingInfoResult;`

## Modules

error | Standard error type for ocl.
types |
util | Utility and debugging functions.

## Structs

Char |
Char2 |
Char3 |
Char4 |
Char8 |
Char16 |
CommandQueueProperties | cl_command_queue_properties - bitfield
DeviceAffinityDomain | cl_device_affinity_domain
DeviceExecCapabilities | cl_device_exec_capabilities - bitfield
DeviceFpConfig | cl_device_fp_config - bitfield
DeviceType | cl_device_type - bitfield
Double |
Double2 |
Double3 |
Double4 |
Double8 |
Double16 |
Float |
Float2 |
Float3 |
Float4 |
Float8 |
Float16 |
Int |
Int2 |
Int3 |
Int4 |
Int8 |
Int16 |
KernelArgTypeQualifier | cl_kernel_arg_type_qualifer
Long |
Long2 |
Long3 |
Long4 |
Long8 |
Long16 |
MapFlags | cl_map_flags - bitfield
MemFlags | cl_mem_flags - bitfield
MemMigrationFlags | cl_mem_migration_flags - bitfield
ProgramBinaryType | cl_program_binary_type
Short |
Short2 |
Short3 |
Short4 |
Short8 |
Short16 |
Uchar |
Uchar2 |
Uchar3 |
Uchar4 |
Uchar8 |
Uchar16 |
Uint |
Uint2 |
Uint3 |
Uint4 |
Uint8 |
Uint16 |
Ulong |
Ulong2 |
Ulong3 |
Ulong4 |
Ulong8 |
Ulong16 |
Ushort |
Ushort2 |
Ushort3 |
Ushort4 |
Ushort8 |
Ushort16 |

## Enums

AddressingMode | cl_addressing_mode
BufferCreateType | cl_buffer_create_type
Cbool | cl_bool
ChannelType | cl_channel_type
ClGlObjectType |
CommandExecutionStatus | command execution status
CommandQueueInfo | cl_command_queue_info
CommandType | cl_command_type
ContextInfo | cl_context_info
ContextInfoOrPropertiesPointerType | cl_context_info + cl_context_properties
ContextProperty | cl_context_info + cl_context_properties
DeviceInfo | cl_device_info
DeviceLocalMemType | cl_device_local_mem_type
DeviceMemCacheType | cl_mem_cache_type
DevicePartitionProperty | [INCOMPLETE] cl_device_partition_property
EventInfo | cl_event_info
FilterMode | cl_filter_mode
GlContextInfo | cl_gl_context_info
GlTextureTarget | specify the texture target type
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
KernelArgAccessQualifier | cl_kernel_arg_access_qualifier
KernelArgAddressQualifier | cl_kernel_arg_address_qualifier
KernelArgInfo | cl_kernel_arg_info
KernelInfo | cl_kernel_info
KernelWorkGroupInfo | cl_kernel_work_group_info
MemInfo | cl_mem_info
MemObjectType | cl_mem_object_type
PlatformInfo | cl_platform_info
Polling | cl_bool: Polling
ProfilingInfo | cl_profiling_info
ProgramBuildInfo | cl_program_build_info
ProgramBuildStatus | cl_build_status
ProgramInfo | cl_program_info
SamplerInfo | cl_sampler_info
Status | The status of an OpenCL API call. Used for returning success/error codes.

## Constants

CL_CGL_SHAREGROUP_KHR_OS_SPECIFIC |
DEVICES_MAX |
DEVICE_AFFINITY_DOMAIN_L1_CACHE |
DEVICE_AFFINITY_DOMAIN_L2_CACHE |
DEVICE_AFFINITY_DOMAIN_L3_CACHE |
DEVICE_AFFINITY_DOMAIN_L4_CACHE |
DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE |
DEVICE_AFFINITY_DOMAIN_NUMA |
DEVICE_TYPE_ACCELERATOR |
DEVICE_TYPE_ALL |
DEVICE_TYPE_CPU |
DEVICE_TYPE_CUSTOM |
DEVICE_TYPE_DEFAULT |
DEVICE_TYPE_GPU |
EXEC_KERNEL |
EXEC_NATIVE_KERNEL |
FP_CORRECTLY_ROUNDED_DIVIDE_SQRT |
FP_DENORM |
FP_FMA |
FP_INF_NAN |
FP_ROUND_TO_INF |
FP_ROUND_TO_NEAREST |
FP_ROUND_TO_ZERO |
FP_SOFT_FLOAT |
KERNEL_ARG_TYPE_CONST |
KERNEL_ARG_TYPE_NONE |
KERNEL_ARG_TYPE_RESTRICT |
KERNEL_ARG_TYPE_VOLATILE |
MAP_READ |
MAP_WRITE |
MAP_WRITE_INVALIDATE_REGION |
MEM_ALLOC_HOST_PTR |
MEM_COPY_HOST_PTR |
MEM_HOST_NO_ACCESS |
MEM_HOST_READ_ONLY |
MEM_HOST_WRITE_ONLY |
MEM_READ_ONLY |
MEM_READ_WRITE |
MEM_USE_HOST_PTR |
MEM_WRITE_ONLY |
MIGRATE_MEM_OBJECT_CONTENT_UNDEFINED |
MIGRATE_MEM_OBJECT_HOST |
PROGRAM_BINARY_TYPE_COMPILED_OBJECT |
PROGRAM_BINARY_TYPE_EXECUTABLE |
PROGRAM_BINARY_TYPE_LIBRARY |
PROGRAM_BINARY_TYPE_NONE |
QUEUE_ON_DEVICE |
QUEUE_ON_DEVICE_DEFAULT |
QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE |
QUEUE_PROFILING_ENABLE |

## Traits

OclNum | A set of traits common to numeric built-in OpenCL scalar and vector primitives.
OclPrm | A primitive type usable within `OpenCL` kernels.
OclScl | A scalar type usable within OpenCL kernels.
OclVec | A vector type usable within `OpenCL` kernels.

## Functions

_complete_user_event | If `event_status` is `CommandExecutionStatus::Complete`, the `cl_event` pointed to by `user_data` will be set to the same.
_dummy_event_callback | Don't be a dummy. Buckle your `_dummy_callback`.
build_program | Builds a program.
compile_program | [UNIMPLEMENTED: Please implement me]
create_buffer ⚠ | Returns a new buffer pointer with size (bytes): `len` * sizeof(T).
create_build_program | Creates, builds, and returns a new program pointer from `src_strings`.
create_command_queue | Returns a new command queue pointer.
create_context | Creates a new context pointer valid for all devices in `device_ids`.
create_context_from_type | Creates a new context pointer for all devices of a specific type.
create_from_gl_buffer ⚠ | Return a buffer pointer from a `OpenGL` buffer object.
create_from_gl_renderbuffer ⚠ | Return a renderbuffer pointer from a `OpenGL` renderbuffer object.
create_from_gl_texture ⚠ | Return a texture2D pointer from a `OpenGL` texture2D object.
create_from_gl_texture_2d ⚠ | Return a texture2D pointer from a `OpenGL` texture2D object.
create_from_gl_texture_3d ⚠ | Return a texture3D pointer from a `OpenGL` texture3D object.
create_image ⚠ | Returns a new image (mem) pointer.
create_kernel | Returns a new kernel.
create_kernels_in_program | [UNIMPLEMENTED: Please implement me]
create_program_with_binary | 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: Please implement me]
create_program_with_source | Creates a new program.
create_sampler | Creates and returns a new sampler object.
create_sub_buffer | Creates a new buffer object (referred to as a sub-buffer object) from an existing buffer object.
create_sub_devices | [UNIMPLEMENTED: Please implement me]
create_user_event | Creates an event not already associated with any command.
default_device_type | Returns the default device type bitflags as specified by environment variable or else `DEVICE_TYPE_ALL`.
default_platform | Returns the default or first platform.
default_platform_idx | Returns the default platform if set by an environment variable or config file.
device_versions | Returns a list of versions for devices.
enqueue_acquire_gl_objects | Acquire OpenCL memory objects (buffers and images) that have been created from OpenGL objects.
enqueue_barrier_with_wait_list | A synchronization point that enqueues a barrier operation.
enqueue_copy_buffer | 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 | 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 | 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 | 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 ⚠ | Enqueues a command to map a region of the buffer object given by `buffer` into the host address space and returns a pointer to this mapped region.
enqueue_map_image ⚠ | Enqueues a command to map a region of the image object given by `image` into the host address space and returns a pointer to this mapped region.
enqueue_marker_with_wait_list | 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 | Enqueues a command to indicate which device a set of memory objects should be associated with.
enqueue_native_kernel | [UNIMPLEMENTED: Please implement me]
enqueue_read_buffer ⚠ | Enqueues a read from device memory referred to by `buffer` to device memory, `data`.
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_release_gl_objects | Release OpenCL memory objects (buffers and images) that have been created from OpenGL objects.
enqueue_task ⚠ | Enqueues a command to execute a kernel on a device.
enqueue_unmap_mem_object | Enqueues a command to unmap a previously mapped region of a memory object.
enqueue_write_buffer ⚠ | Enqueues a write from host memory, `data`, to device memory referred to by `buffer`.
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.
event_is_complete | Returns true if an event is complete, false if not complete.
event_status | Returns the status of `event`.
finish | Waits for a queue to finish.
flush | Flushes a command queue.
get_command_queue_info | Returns information about a command queue
get_context_info | Returns various kinds of context information.
get_context_platform | Returns the platform for a context.
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_extension_function_address_for_platform ⚠ | Returns the address of the extension function named by `func_name` for a given platform.
get_gl_context_info_khr | [INOPERATIVE: Needs troubleshooting] Returns OpenGL context information.
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: Please implement me]
program_build_err | If the program pointed to by `cl_program` for any of the devices listed in `device_ids` has a build log of any length, it will be returned as an errcode result.
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 `callback_trigger` status is reached.
set_kernel_arg | Sets the argument value for the kernel argument at `index`.
set_mem_object_destructor_callback | [UNIMPLEMENTED: Please implement me]
set_user_event_status | Updates a user events status.
verify_context | Verifies that the `context` is in fact a context object pointer.
wait_for_event | Blocks until an event is complete.
wait_for_events | Blocks until the first `num_events` events in `event_list` are complete.

## Type Definitions

BuildProgramCallbackFn |
CreateContextCallbackFn |
EventCallbackFn |
UserDataPtr |

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)