Struct ocl::builders::KernelBuilder

pub struct KernelBuilder<'b> { /* fields omitted */ }

A kernel builder.

Examples

// Create a kernel:
let kernel = Kernel::builder()
    .program(&program)
    .name("process")
    .queue(queue.clone())
    .global_work_size(&gws_patch_count)
    .arg(&(patch_size as i32))
    .arg(&source_buffer)
    .arg(&destination_buffer)
    .build()?;

Re-use and clone:

// Create a builder for re-use:
let builder = Kernel::builder()
    .program(&program)
    .name("process")
    .queue(queue.clone())
    .global_work_size([512, 64, 64])
    .arg(&(patch_size as i32))
    .arg(&source_buffer)
    .arg_named("dest", &destination_buffer);

// Create multiple kernels using the same builder:
let kernel_0 = builder.build()?;
let kernel_1 = builder.build()?;

// Clone the builder:
let mut builder_clone = builder.clone();

// Modify a default parameter:
builder_clone.global_work_size([1024, 128, 128]);

// Create another kernel using the cloned builder:
let kernel_2 = builder_clone.build()?;

// Modify one of the arguments using the created kernel directly
// (arguments cannot be modified using the builder):
kernel_2.set_arg("dest", &alternate_destination_buffer)?;

// Arguments can also be referred to by index:
kernel_2.set_arg(1, &alternate_source_buffer)?;

Methods

impl<'b> KernelBuilder<'b>

pub fn new() -> KernelBuilder<'b>

Returns a new kernel builder.

pub fn program<'s>(
    &'s mut self,
    program: &'b Program
) -> &'s mut KernelBuilder<'b>

Specifies a program object with a successfully built executable.

pub fn name<'s, S>(&'s mut self, name: S) -> &'s mut KernelBuilder<'b> where
    S: Into<String>, 

Specifies a function name in the program declared with the __kernel qualifier (e.g. __kernel void add_values(...).

pub fn queue<'s>(&'s mut self, queue: Queue) -> &'s mut KernelBuilder<'b>

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.

pub fn gwo<'s, D: Into<SpatialDims>>(
    &'s mut self,
    gwo: D
) -> &'s mut KernelBuilder<'b>

Deprecated since 0.18.0

: Use ::global_work_offset instead.

Sets the default global work offset.

Used when enqueuing kernel commands. Superseded if specified while building a queue command with ::cmd.

pub fn gws<'s, D: Into<SpatialDims>>(
    &'s mut self,
    gws: D
) -> &'s mut KernelBuilder<'b>

Deprecated since 0.18.0

: Use ::global_work_size instead.

Sets the default global work size.

Used when enqueuing kernel commands. Superseded if specified while building a queue command with ::cmd.

pub fn lws<'s, D: Into<SpatialDims>>(
    &'s mut self,
    lws: D
) -> &'s mut KernelBuilder<'b>

Deprecated since 0.18.0

: Use ::local_work_size instead.

Sets the default local work size.

Used when enqueuing kernel commands. Superseded if specified while building a queue command with ::cmd.

pub fn global_work_offset<'s, D: Into<SpatialDims>>(
    &'s mut self,
    gwo: D
) -> &'s mut KernelBuilder<'b>

Sets the default global work offset.

Used when enqueuing kernel commands. Superseded if specified while building a queue command with ::cmd.

pub fn global_work_size<'s, D: Into<SpatialDims>>(
    &'s mut self,
    gws: D
) -> &'s mut KernelBuilder<'b>

Sets the default global work size.

Used when enqueuing kernel commands. Superseded if specified while building a queue command with ::cmd.

pub fn local_work_size<'s, D: Into<SpatialDims>>(
    &'s mut self,
    lws: D
) -> &'s mut KernelBuilder<'b>

Sets the default local work size.

Used when enqueuing kernel commands. Superseded if specified while building a queue command with ::cmd.

pub fn arg<'s, T, A>(&'s mut self, arg: A) -> &'s mut KernelBuilder<'b> where
    T: OclPrm,
    A: Into<ArgValConverter<'b, T>>, 

Adds a new Buffer, Image, scalar, or vector argument to the kernel.

The argument is added to the bottom of the argument order.

Example

let kern = ocl_pq.kernel_builder("multiply_by_scalar")
    .arg(&100.0f32)
    .arg(&source_buffer)
    .arg(&result_buffer)
    .build()?;

pub fn arg_buf<'s, T, M>(
    &'s mut self,
    buffer: &'b M
) -> &'s mut KernelBuilder<'b> where
    T: OclPrm,
    M: 'b + AsMem<T> + MemCmdAll, 

Deprecated since 0.18

: Use ::arg instead.

Adds a new argument to the kernel specifying the buffer object represented by 'buffer'.

The argument is added to the bottom of the argument order.

pub fn arg_img<'s, T, M>(
    &'s mut self,
    image: &'b M
) -> &'s mut KernelBuilder<'b> where
    T: OclPrm,
    M: 'b + AsMem<T> + MemCmdAll, 

Deprecated since 0.18

: Use ::arg instead.

Adds a new argument to the kernel specifying the image object represented by 'image'.

The argument is added to the bottom of the argument order.

pub fn arg_smp<'s>(
    &'s mut self,
    sampler: &'b Sampler
) -> &'s mut KernelBuilder<'b>

Deprecated since 0.18

: Use ::arg_sampler instead.

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

pub fn arg_scl<'s, T>(&'s mut self, scalar: T) -> &'s mut KernelBuilder<'b> where
    T: OclPrm, 

Deprecated since 0.18

: Use ::arg instead.

Adds a new argument specifying the value: scalar.

The argument is added to the bottom of the argument order.

pub fn arg_vec<'s, T>(&'s mut self, vector: T) -> &'s mut KernelBuilder<'b> where
    T: OclPrm, 

Deprecated since 0.18

: Use ::arg instead.

Adds a new argument specifying the value: vector.

The argument is added to the bottom of the argument order.

pub fn arg_loc<'s, T>(&'s mut self, length: usize) -> &'s mut KernelBuilder<'b> where
    T: OclPrm, 

Deprecated since 0.18

: Use ::arg_local instead.

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

The argument is added to the bottom of the argument order.

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

pub fn arg_sampler<'s>(
    &'s mut self,
    sampler: &'b Sampler
) -> &'s mut KernelBuilder<'b>

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

pub fn arg_local<'s, T>(
    &'s mut self,
    length: usize
) -> &'s mut KernelBuilder<'b> where
    T: OclPrm, 

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

The argument is added to the bottom of the argument order.

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

pub fn arg_named<'s, T, A>(
    &'s mut self,
    name: &'static str,
    arg: A
) -> &'s mut KernelBuilder<'b> where
    T: OclPrm,
    A: Into<ArgValConverter<'b, T>>, 

Adds a new named Buffer, Image, scalar, or vector argument to the kernel.

The argument is added to the bottom of the argument order.

To set a Buffer or Image argument to None (null), you must use a type annotation (e.g. None::<&Buffer<f32>>). Scalar and vector arguments may not be null; use zero (e.g. &0) instead.

Named arguments can be modified later using ::set_arg().

Example

// Create a kernel with arguments corresponding to those in the kernel.
// One argument will be 'named':
let kern = ocl_pq.kernel_builder("multiply_by_scalar")
    .arg(&COEFF)
    .arg(&source_buffer)
    .arg_named("result", None::<&Buffer<f32>>)
    .build()?;

// Set our named argument. The Option<_> wrapper is, well... optional:
kern.set_arg("result", &result_buffer)?;
// We can also set arguments (named or not) by index:
kern.set_arg(2, &result_buffer)?;

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

Deprecated since 0.18

: Use ::arg_named instead.

Adds a new named argument specifying the buffer object represented by 'buffer'.

The argument is added to the bottom of the argument order.

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

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

Deprecated since 0.18

: Use ::arg_named instead.

Adds a new named argument specifying the image object represented by 'image'.

The argument is added to the bottom of the argument order.

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

pub fn arg_smp_named<'s>(
    &'s mut self,
    name: &'static str,
    sampler_opt: Option<&'b Sampler>
) -> &'s mut KernelBuilder<'b>

Deprecated since 0.18

: Use ::arg_sampler_named instead.

Adds a new named argument specifying the sampler object represented by 'sampler'.

The argument is added to the bottom of the argument order.

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

pub fn arg_scl_named<'s, T>(
    &'s mut self,
    name: &'static str,
    scalar: T
) -> &'s mut KernelBuilder<'b> where
    T: OclPrm, 

Deprecated since 0.18

: Use ::arg_named instead.

Adds a new named argument specifying the value: scalar.

The argument is added to the bottom of the argument order.

Scalar arguments may not be null, use zero (e.g. &0) instead.

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

pub fn arg_vec_named<'s, T>(
    &'s mut self,
    name: &'static str,
    vector: T
) -> &'s mut KernelBuilder<'b> where
    T: OclPrm, 

Deprecated since 0.18

: Use ::arg_named instead.

Adds a new named argument specifying the value: vector.

The argument is added to the bottom of the argument order.

Vector arguments may not be null, use zero (e.g. &0) instead.

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

pub fn arg_sampler_named<'s>(
    &'s mut self,
    name: &'static str,
    sampler_opt: Option<&'b Sampler>
) -> &'s mut KernelBuilder<'b>

Adds a new named argument specifying the sampler object represented by 'sampler'.

The argument is added to the bottom of the argument order.

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

pub unsafe fn disable_mem_arg_retention<'s>(
    &'s mut self
) -> &'s mut KernelBuilder<'b>

Specifies whether or not to store a copy of memory objects (Buffer and Image).

Safety

Disabling memory object argument retention can lead to a misleading error message or a difficult to debug segfault (depending on the platform) if a memory object is dropped before a kernel referring to it is enqueued. Only disable this if you are certain all of the memory objects set as kernel arguments will outlive the Kernel itself.

pub unsafe fn disable_arg_type_check<'s>(
    &'s mut self
) -> &'s mut KernelBuilder<'b>

Disables argument type checking when setting arguments.

Because the performance cost of argument type checking is negligible, disabling is not recommended.

Argument type checking will automatically be disabled if any of the devices in use do not support OpenCL version 1.2 or higher or if argument information is not available on the associated platform.

pub fn build(&self) -> OclResult<Kernel>

Builds and returns a new Kernel

Trait Implementations

impl<'b> Debug for KernelBuilder<'b>

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

Formats the value using the given formatter.