Struct ocl::Kernel

pub struct Kernel { /* fields omitted */ }

A kernel which represents a 'procedure'.

Corresponds to code which must have already been compiled into a program.

Set arguments using any of the ::arg... (builder-style) or ::set_arg... functions or use ::set_arg to set arguments by index.

Kernel includes features that a raw OpenCL kernel does not, including:

1. Type-checked arguments (not just size-checked)
2. Named arguments (with a &'static str name)
3. Prevention of a potential (difficult to debug) segfault if a buffer or image used by a kernel is dropped prematurely.
4. Stored defaults for the:
   • Queue
   • Global Work Offset
   • Global Work Size
   • Local Work Size

Methods

impl Kernel

fn new<S: Into<String>>(name: S, program: &Program) -> OclResult<Kernel>

Returns a new kernel.

fn queue(self, queue: Queue) -> Kernel

Sets the default queue to be used by all subsequent enqueue commands unless otherwise changed (with ::set_default_queue) or overridden (by ::cmd().queue(...)...).

The queue must be associated with a device associated with the kernel's program.

fn gwo<D: Into<SpatialDims>>(self, gwo: D) -> Kernel

Sets the default global work offset (builder-style).

Used when enqueuing kernel commands. Superseded if specified while making a call to enqueue or building a queue command with ::cmd.

fn gws<D: Into<SpatialDims>>(self, gws: D) -> Kernel

Sets the default global work size (builder-style).

Used when enqueuing kernel commands. Superseded if specified while making a call to enqueue or building a queue command with ::cmd.

fn lws<D: Into<SpatialDims>>(self, lws: D) -> Kernel

Sets the default local work size (builder-style).

Used when enqueuing kernel commands. Superseded if specified while making a call to enqueue or building a queue command with ::cmd.

fn arg_buf<T, M>(self, buffer: M) -> Kernel where
    T: OclPrm + 'static,
    M: AsMem<T> + MemCmdAll, 

Adds a new argument to the kernel specifying the buffer object represented by 'buffer' (builder-style). Argument is added to the bottom of the argument order.

fn arg_img<T, M>(self, image: M) -> Kernel where
    T: OclPrm,
    M: AsMem<T> + MemCmdAll, 

Adds a new argument to the kernel specifying the image object represented by 'image' (builder-style). Argument is added to the bottom of the argument order.

fn arg_smp(self, sampler: &Sampler) -> Kernel

Adds a new argument to the kernel specifying the sampler object represented by 'sampler' (builder-style). Argument is added to the bottom of the argument order.

fn arg_scl<T: OclPrm>(self, scalar: T) -> Kernel where
    T: OclPrm + 'static, 

Adds a new argument specifying the value: scalar (builder-style). Argument is added to the bottom of the argument order.

fn arg_vec<T: OclPrm>(self, vector: T) -> Kernel where
    T: OclPrm + 'static, 

Adds a new argument specifying the value: vector (builder-style). Argument is added to the bottom of the argument order.

fn arg_loc<T: OclPrm>(self, length: usize) -> Kernel where
    T: OclPrm + 'static, 

Adds a new argument specifying the allocation of a local variable of size length * sizeof(T) bytes (builder_style).

Local variables are used to share data between work items in the same workgroup.

fn arg_scl_named<T: OclPrm>(
    self,
    name: &'static str,
    scalar_opt: Option<T>
) -> Kernel where
    T: OclPrm + 'static, 

Adds a new named argument (in order) specifying the value: scalar (builder-style).

Named arguments can be easily modified later using ::set_arg_scl_named().

fn arg_vec_named<T: OclPrm>(
    self,
    name: &'static str,
    vector_opt: Option<T>
) -> Kernel where
    T: OclPrm + 'static, 

Adds a new named argument (in order) specifying the value: vector (builder-style).

Named arguments can be easily modified later using ::set_arg_vec_named().

fn arg_buf_named<T, M>(
    self,
    name: &'static str,
    buffer_opt: Option<M>
) -> Kernel where
    T: OclPrm + 'static,
    M: AsMem<T> + MemCmdAll, 

Adds a new named argument specifying the buffer object represented by 'buffer' (builder-style). Argument is added to the bottom of the argument order.

Named arguments can be easily modified later using ::set_arg_buf_named().

fn arg_img_named<T, M>(self, name: &'static str, image_opt: Option<M>) -> Kernel where
    T: OclPrm,
    M: AsMem<T> + MemCmdAll, 

Adds a new named argument specifying the image object represented by 'image' (builder-style). Argument is added to the bottom of the argument order.

Named arguments can be easily modified later using ::set_arg_img_named().

fn arg_smp_named(
    self,
    name: &'static str,
    sampler_opt: Option<&Sampler>
) -> Kernel

Adds a new named argument specifying the sampler object represented by 'sampler' (builder-style). Argument is added to the bottom of the argument order.

Named arguments can be easily modified later using ::set_arg_smp_named().

fn set_arg_scl_named<'a, T>(
    &'a mut self,
    name: &'static str,
    scalar: T
) -> OclResult<&'a mut Kernel> where
    T: OclPrm + 'static, 

Modifies the kernel argument named: name.

Panics [FIXME]

fn set_arg_vec_named<'a, T>(
    &'a mut self,
    name: &'static str,
    vector: T
) -> OclResult<&'a mut Kernel> where
    T: OclPrm + 'static, 

Modifies the kernel argument named: name.

Panics [FIXME]

fn set_arg_buf_named<'a, T, M>(
    &'a mut self,
    name: &'static str,
    buffer_opt: Option<M>
) -> OclResult<&'a mut Kernel> where
    T: OclPrm + 'static,
    M: AsMem<T> + MemCmdAll, 

Modifies the kernel argument named: name.

Panics [FIXME]

fn set_arg_img_named<'a, T, M>(
    &'a mut self,
    name: &'static str,
    image_opt: Option<M>
) -> OclResult<&'a mut Kernel> where
    T: OclPrm + 'static,
    M: AsMem<T> + MemCmdAll, 

Modifies the kernel argument named: name.

Panics [FIXME]

fn set_arg_smp_named<'a, T: OclPrm>(
    &'a mut self,
    name: &'static str,
    sampler_opt: Option<&Sampler>
) -> OclResult<&'a mut Kernel>

Sets the value of a named sampler argument.

Panics [FIXME]

fn cmd(&self) -> KernelCmd

Returns a command builder which is used to chain parameters of an 'enqueue' command together.

fn enq(&self) -> OclResult<()>

Enqueues this kernel on the default queue and returns the result.

Shorthand for .cmd().enq()

Safety

All kernel code must be considered unsafe. Therefore the act of calling this function contains implied unsafety even though the API itself is safe. How best to express that without the ambiguity of being marked unsafe while maintaining zero extra runtime overhead is still under consideration. Please provide feedback by filing an issue if you have any thoughts on the matter.

fn set_default_queue(&mut self, queue: Queue) -> &mut Kernel

Changes the default queue.

Returns a ref for chaining i.e.:

kernel.set_default_queue(queue).enqueue(....);

Even when used as above, the queue is changed permanently, not just for the one call. Changing the queue is cheap so feel free to change as often as needed.

If you want to change the queue for only a single call, use: ::cmd.queue(...)...enq()...

The new queue must be associated with a device associated with the kernel's program.

fn default_queue(&self) -> Option<&Queue>

Returns the default queue for this kernel.

fn get_gwo(&self) -> SpatialDims

Returns the default global work offset.

fn get_gws(&self) -> SpatialDims

Returns the default global work size.

fn get_lws(&self) -> SpatialDims

Returns the default local work size.

fn new_arg_count(&self) -> u32

Returns the number of arguments specified for this kernel.

fn core_as_ref(&self) -> &KernelCore

Deprecated since 0.13.0

: Use ::core instead.

Returns a reference to the core pointer wrapper, usable by functions in the core module.

fn core(&self) -> &KernelCore

Returns a reference to the core pointer wrapper, usable by functions in the core module.

fn info(&self, info_kind: KernelInfo) -> KernelInfoResult

Returns information about this kernel.

fn arg_info(
    &self,
    arg_index: u32,
    info_kind: KernelArgInfo
) -> KernelArgInfoResult

Returns argument information for this kernel.

fn wg_info(
    &self,
    device: Device,
    info_kind: KernelWorkGroupInfo
) -> KernelWorkGroupInfoResult

Returns work group information for this kernel.

fn name(&self) -> String

Returns the name of this kernel.

fn num_args(&self) -> u32

Returns the number of arguments this kernel has.

fn named_arg_idx(&self, name: &'static str) -> Option<u32>

Returns the argument index of a named argument if it exists.

fn verify_arg_type<T: OclPrm + Any>(&self, arg_index: u32) -> OclResult<()>

Verifies that a type matches the kernel arg info:

unsafe fn set_arg_unchecked<T: OclPrm>(
    &mut self,
    arg_idx: u32,
    arg: KernelArg<T>
) -> OclResult<()>

Sets an argument by index without checks of any kind.

Setting buffer or image (cl_mem) arguments this way may cause segfaults or errors if the buffer goes out of scope at any point before this kernel is dropped.

This method also bypasses the check to determine if the type you are passing matches the type defined in your kernel.

Methods from Deref<Target = KernelCore>

fn as_ptr(&self) -> *mut c_void

Returns a pointer, do not store it.

fn program(&self) -> Result<Program, Error>

Returns the program associated with this kernel.

fn devices(&self) -> Result<Vec<DeviceId>, Error>

Trait Implementations

impl Debug for Kernel

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Clone for Kernel

fn clone(&self) -> Kernel

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Display for Kernel

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Deref for Kernel

type Target = KernelCore

The resulting type after dereferencing

fn deref(&self) -> &KernelCore

The method called to dereference a value

impl DerefMut for Kernel

fn deref_mut(&mut self) -> &mut KernelCore

The method called to mutably dereference a value