Struct ocl::builders::ImageBuilder

#[must_use = "builders do nothing unless \'::build\' is called"]
pub struct ImageBuilder<'a, T> where
    T: 'a,  { /* fields omitted */ }

A builder for Image.

Methods

impl<'a, T> ImageBuilder<'a, T> where
    T: 'a + OclPrm, 

pub fn new() -> ImageBuilder<'a, T>

Returns a new ImageBuilder with very basic defaults.

Defaults

• Flags:

ocl::MEM_READ_WRITE

• Image Format:

ocl::ImageFormat {
   channel_order: ocl::ImageChannelOrder::Rgba,
   channel_data_type: ocl::ImageChannelDataType::SnormInt8,
}

• Descriptor (stores everything else - width, height, pitch, etc.):

ImageDescriptor::new(MemObjectType::Image1d, 0, 0, 0, 0, 0, 0, None)

Reference

See the [official SDK documentation] for more information.

Some descriptions here are adapted from various SDK docs.

pub fn context<'o>(self, context: &'o Context) -> ImageBuilder<'a, T> where
    'o: 'a, 

Sets the context with which to associate the buffer.

May not be used in combination with ::queue (use one or the other).

pub fn queue<'b>(self, default_queue: Queue) -> ImageBuilder<'a, T>

Sets the default queue.

If this is set, the context associated with the default_queue will be used when creating the buffer (use one or the other).

pub fn flags<'b>(self, flags: MemFlags) -> ImageBuilder<'a, T>

Sets the flags used when creating the image.

Defaults to flags::MEM_READ_WRITE aka. MemFlags::new().read_write() if this is not set. See the SDK Docs for more information about flags. Note that the names of all flags in this library have the CL_ prefix removed for brevity.

Panics

Due to its unsafety, setting the MEM_USE_HOST_PTR/MemFlags::new()::use_host_ptr() flag will cause a panic. Use the ::use_host_slice method instead.

pub unsafe fn use_host_slice<'d>(
    self,
    host_slice: &'d [T]
) -> ImageBuilder<'a, T> where
    'd: 'a, 

Specifies a region of host memory to use as storage for the image.

OpenCL implementations are allowed to cache the image contents pointed to by host_slice in device memory. This cached copy can be used when kernels are executed on a device.

The result of OpenCL commands that operate on multiple image objects created with the same host_slice or overlapping host regions is considered to be undefined

Refer to the description of the alignment rules for host_slice for memory objects (buffer and images) created using this method.

Automatically sets the flags::MEM_USE_HOST_PTR aka. MemFlags::new().use_host_ptr() flag.

Panics

::copy_host_slice or ::use_host_slice must not have already been called.

Safety

The caller must ensure that host_slice lives until the image is destroyed. The caller must also ensure that only one image uses host_slice and that it is not tampered with inappropriately.

pub fn copy_host_slice<'d>(self, host_slice: &'d [T]) -> ImageBuilder<'a, T> where
    'd: 'a, 

Specifies a region of memory to copy into the image upon creation.

Automatically sets the flags::MEM_COPY_HOST_PTR aka. MemFlags::new().copy_host_ptr() flag.

Panics

::copy_host_slice or ::use_host_slice must not have already been called.

pub fn channel_order(self, order: ImageChannelOrder) -> ImageBuilder<'a, T>

pub fn channel_data_type(
    self,
    data_type: ImageChannelDataType
) -> ImageBuilder<'a, T>

pub fn image_type(self, image_type: MemObjectType) -> ImageBuilder<'a, T>

Sets the type of image (technically the type of memory buffer).

Describes the image type and must be either Image1d, Image1dBuffer, Image1dArray, Image2d, Image2dArray, or Image3d.

pub fn dims<D>(self, dims: D) -> ImageBuilder<'a, T> where
    D: Into<SpatialDims>, 

The width, height, and depth of an image or image array:

Some notes adapted from SDK docs:

Width

The width of the image in pixels. For a 2D image and image array, the image width must be ≤ DeviceInfo::Image2dMaxWidth. For a 3D image, the image width must be ≤ DeviceInfo::Image3dMaxWidth. For a 1D image buffer, the image width must be ≤ DeviceInfo::ImageMaxBufferSize. For a 1D image and 1D image array, the image width must be ≤ DeviceInfo::Image2dMaxWidth.

Height

The height of the image in pixels. This is only used if the image is a 2D, 3D or 2D image array. For a 2D image or image array, the image height must be ≤ DeviceInfo::Image2dMaxHeight. For a 3D image, the image height must be ≤ DeviceInfo::Image3dMaxHeight.

Depth

image_depth The depth of the image in pixels. This is only used if the image is a 3D image and must be a value ≥ 1 and ≤ DeviceInfo::Image3dMaxDepth.

Examples

• To set the dimensions of a 2d image use: SpatialDims::Two(width, height).
• To set the dimensions of a 2d image array use: SpatialDims::Three(width, height, array_length).
• To set the dimensions of a 3d image use: SpatialDims::Three(width, height, depth).

pub fn array_size(self, array_size: usize) -> ImageBuilder<'a, T>

Image array size.

The number of images in the image array. This is only used if the image is a 1D or 2D image array. The values for image_array_size, if specified, must be a value ≥ 1 and ≤ DeviceInfo::ImageMaxArraySize.

Note that reading and writing 2D image arrays from a kernel with image_array_size = 1 may be lower performance than 2D images.

pub fn row_pitch_bytes(self, row_pitch: usize) -> ImageBuilder<'a, T>

Image row pitch.

The scan-line pitch in bytes. This must be 0 if host data is None and can be either 0 or ≥ image_width * size of element in bytes if host data is not None. If host data is not None and image_row_pitch = 0, image_row_pitch is calculated as image_width * size of element in bytes. If image_row_pitch is not 0, it must be a multiple of the image element size in bytes.

pub fn slc_pitch_bytes(self, slc_pitch: usize) -> ImageBuilder<'a, T>

Image slice pitch.

The size in bytes of each 2D slice in the 3D image or the size in bytes of each image in a 1D or 2D image array. This must be 0 if host data is None. If host data is not None, image_slice_pitch can be either 0 or ≥ image_row_pitch * image_height for a 2D image array or 3D image and can be either 0 or ≥ image_row_pitch for a 1D image array. If host data is not None and image_slice_pitch = 0, image_slice_pitch is calculated as image_row_pitch * image_height for a 2D image array or 3D image and image_row_pitch for a 1D image array. If image_slice_pitch is not 0, it must be a multiple of the image_row_pitch.

pub fn buffer_sync(self, buffer: MemCore) -> ImageBuilder<'a, T>

Buffer synchronization.

Refers to a valid buffer memory object if image_type is MemObjectType::Image1dBuffer. Otherwise it must be None (default). For a 1D image buffer object, the image pixels are taken from the buffer object's data store. When the contents of a buffer object's data store are modified, those changes are reflected in the contents of the 1D image buffer object and vice-versa at corresponding sychronization points. The image_width * size of element in bytes must be ≤ size of buffer object data store.

pub fn image_format(self, image_format: ImageFormat) -> ImageBuilder<'a, T>

Specifies the image pixel format.

If unspecified, defaults to:

ImageFormat {
   channel_order: ImageChannelOrder::Rgba,
   channel_data_type: ImageChannelDataType::SnormInt8,
}

pub unsafe fn image_desc(
    self,
    image_desc: ImageDescriptor
) -> ImageBuilder<'a, T>

Specifies the image descriptor containing a number of important settings.

If unspecified (not recommended), defaults to:

ImageDescriptor {
    image_type: MemObjectType::Image1d,
    image_width: 0,
    image_height: 0,
    image_depth: 0,
    image_array_size: 0,
    image_row_pitch: 0,
    image_slice_pitch: 0,
    num_mip_levels: 0,
    num_samples: 0,
    buffer: None,
}

If you are unsure, just set the first four by using ImageDescriptor::new. Ex.:

ocl::Image::builder()
   .image_desc(ocl::ImageDescriptor::new(
      ocl::MemObjectType::Image2d, 1280, 800, 1))
   ...
   ...
   .build()

Setting this overwrites any previously set type, dimensions, array size, pitch, etc.

pub fn build(self) -> OclCoreResult<Image<T>>

Builds with no host side image data memory specified and returns a new Image.