Struct ocl::builders::KernelBuilder
source · pub struct KernelBuilder<'b> { /* private fields */ }
Expand description
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)?;
Implementations§
source§impl<'b> KernelBuilder<'b>
impl<'b> KernelBuilder<'b>
sourcepub fn new() -> KernelBuilder<'b>
pub fn new() -> KernelBuilder<'b>
Returns a new kernel builder.
sourcepub fn program<'s>(
&'s mut self,
program: &'b Program
) -> &'s mut KernelBuilder<'b>
pub fn program<'s>( &'s mut self, program: &'b Program ) -> &'s mut KernelBuilder<'b>
Specifies a program object with a successfully built executable.
sourcepub fn name<'s, S>(&'s mut self, name: S) -> &'s mut KernelBuilder<'b>
pub fn name<'s, S>(&'s mut self, name: S) -> &'s mut KernelBuilder<'b>
Specifies a function name in the program declared with the __kernel
qualifier (e.g. __kernel void add_values(...
).
sourcepub fn queue<'s>(&'s mut self, queue: Queue) -> &'s mut KernelBuilder<'b>
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.
sourcepub 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.
pub fn gwo<'s, D: Into<SpatialDims>>( &'s mut self, gwo: D ) -> &'s mut KernelBuilder<'b>
::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
.
sourcepub 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.
pub fn gws<'s, D: Into<SpatialDims>>( &'s mut self, gws: D ) -> &'s mut KernelBuilder<'b>
::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
.
sourcepub 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.
pub fn lws<'s, D: Into<SpatialDims>>( &'s mut self, lws: D ) -> &'s mut KernelBuilder<'b>
::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
.
sourcepub fn global_work_offset<'s, D: Into<SpatialDims>>(
&'s mut self,
gwo: D
) -> &'s mut KernelBuilder<'b>
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
.
sourcepub fn global_work_size<'s, D: Into<SpatialDims>>(
&'s mut self,
gws: D
) -> &'s mut KernelBuilder<'b>
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
.
sourcepub fn local_work_size<'s, D: Into<SpatialDims>>(
&'s mut self,
lws: D
) -> &'s mut KernelBuilder<'b>
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
.
sourcepub fn arg<'s, T, A>(&'s mut self, arg: A) -> &'s mut KernelBuilder<'b>
pub fn arg<'s, T, A>(&'s mut self, arg: A) -> &'s mut KernelBuilder<'b>
sourcepub fn arg_buf<'s, T, M>(
&'s mut self,
buffer: &'b M
) -> &'s mut KernelBuilder<'b>
👎Deprecated since 0.18.0: Use ::arg instead.
pub fn arg_buf<'s, T, M>( &'s mut self, buffer: &'b M ) -> &'s mut KernelBuilder<'b>
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.
sourcepub fn arg_img<'s, T, M>(
&'s mut self,
image: &'b M
) -> &'s mut KernelBuilder<'b>
👎Deprecated since 0.18.0: Use ::arg instead.
pub fn arg_img<'s, T, M>( &'s mut self, image: &'b M ) -> &'s mut KernelBuilder<'b>
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.
sourcepub fn arg_smp<'s>(
&'s mut self,
sampler: &'b Sampler
) -> &'s mut KernelBuilder<'b>
👎Deprecated since 0.18.0: Use ::arg_sampler instead.
pub fn arg_smp<'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.
sourcepub fn arg_scl<'s, T>(&'s mut self, scalar: T) -> &'s mut KernelBuilder<'b>where
T: OclPrm,
👎Deprecated since 0.18.0: Use ::arg instead.
pub fn arg_scl<'s, T>(&'s mut self, scalar: T) -> &'s mut KernelBuilder<'b>where
T: OclPrm,
Adds a new argument specifying the value: scalar
.
The argument is added to the bottom of the argument order.
sourcepub fn arg_vec<'s, T>(&'s mut self, vector: T) -> &'s mut KernelBuilder<'b>where
T: OclPrm,
👎Deprecated since 0.18.0: Use ::arg instead.
pub fn arg_vec<'s, T>(&'s mut self, vector: T) -> &'s mut KernelBuilder<'b>where
T: OclPrm,
Adds a new argument specifying the value: vector
.
The argument is added to the bottom of the argument order.
sourcepub fn arg_loc<'s, T>(&'s mut self, length: usize) -> &'s mut KernelBuilder<'b>where
T: OclPrm,
👎Deprecated since 0.18.0: Use ::arg_local instead.
pub fn arg_loc<'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.
sourcepub fn arg_sampler<'s>(
&'s mut self,
sampler: &'b Sampler
) -> &'s mut KernelBuilder<'b>
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.
sourcepub fn arg_local<'s, T>(
&'s mut self,
length: usize
) -> &'s mut KernelBuilder<'b>where
T: OclPrm,
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.
sourcepub fn arg_named<'s, T, S, A>(
&'s mut self,
name: S,
arg: A
) -> &'s mut KernelBuilder<'b>
pub fn arg_named<'s, T, S, A>( &'s mut self, name: S, arg: A ) -> &'s mut KernelBuilder<'b>
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)?;
sourcepub fn arg_buf_named<'s, T, S, M>(
&'s mut self,
name: S,
buffer_opt: Option<&'b M>
) -> &'s mut KernelBuilder<'b>
👎Deprecated since 0.18.0: Use ::arg_named instead.
pub fn arg_buf_named<'s, T, S, M>( &'s mut self, name: S, buffer_opt: Option<&'b M> ) -> &'s mut KernelBuilder<'b>
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()
.
sourcepub fn arg_img_named<'s, T, S, M>(
&'s mut self,
name: S,
image_opt: Option<&'b M>
) -> &'s mut KernelBuilder<'b>
👎Deprecated since 0.18.0: Use ::arg_named instead.
pub fn arg_img_named<'s, T, S, M>( &'s mut self, name: S, image_opt: Option<&'b M> ) -> &'s mut KernelBuilder<'b>
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()
.
sourcepub fn arg_smp_named<'s, S>(
&'s mut self,
name: S,
sampler_opt: Option<&'b Sampler>
) -> &'s mut KernelBuilder<'b>
👎Deprecated since 0.18.0: Use ::arg_sampler_named instead.
pub fn arg_smp_named<'s, S>( &'s mut self, name: S, 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()
.
sourcepub 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.0: Use ::arg_named instead.
pub fn arg_scl_named<'s, T>(
&'s mut self,
name: &'static str,
scalar: T
) -> &'s mut KernelBuilder<'b>where
T: OclPrm,
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()
.
sourcepub 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.0: Use ::arg_named instead.
pub fn arg_vec_named<'s, T>(
&'s mut self,
name: &'static str,
vector: T
) -> &'s mut KernelBuilder<'b>where
T: OclPrm,
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()
.
sourcepub fn arg_sampler_named<'s>(
&'s mut self,
name: &'static str,
sampler_opt: Option<&'b Sampler>
) -> &'s mut KernelBuilder<'b>
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()
.
sourcepub unsafe fn disable_mem_arg_retention<'s>(
&'s mut self
) -> &'s mut KernelBuilder<'b>
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.
sourcepub unsafe fn disable_arg_type_check<'s>(
&'s mut self
) -> &'s mut KernelBuilder<'b>
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.