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.

Reexports

pub extern crate cl_sys as ffi;

pub use self::error::Error;

pub use self::error::Result;

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::enums::EmptyInfoResult;

pub use self::types::enums::KernelArg;

pub use self::types::enums::PlatformInfoResult;

pub use self::types::enums::DeviceInfoResult;

pub use self::types::enums::ContextInfoResult;

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
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

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]
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 ^⚠	[UNTESTED] Return a buffer pointer from a `OpenGL` buffer object.
create_from_gl_renderbuffer ^⚠	[UNTESTED] Return a renderbuffer pointer from a `OpenGL` renderbuffer object.
create_from_gl_texture ^⚠	[UNTESTED] Return a texture2D pointer from a `OpenGL` texture2D object.
create_from_gl_texture_2d ^⚠	[UNTESTED] [DEPRICATED] Return a texture2D pointer from a `OpenGL` texture2D object.
create_from_gl_texture_3d ^⚠	[UNTESTED] [DEPRICATED] 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]
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	Creates a new buffer object (referred to as a sub-buffer object) from an existing buffer object.
create_sub_devices	[UNIMPLEMENTED]
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_buffer	[UNTESTED] Enqueue acquire OpenCL memory objects 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	[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 ^⚠	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 ^⚠	[UNTESTED] 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	[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 `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_buffer	[UNTESTED] Enqueue release OpenCL memory objects that have been created from `OpenGL` objects.
enqueue_task	[UNTESTED] 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 ^⚠	[UNTESTED] Returns the address of the extension function named by `func_name` for a given platform.
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 `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 a specific argument of a kernel.
set_mem_object_destructor_callback	[UNIMPLEMENTED]
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