Struct ocl::builders::ImageBuilder [−] [src]

#[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, 
[src]

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.

Sets the context with which to associate the buffer.

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

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

Sets the flags for the memory to be created.

Setting this overwrites any previously set flags. To combine them, use the bitwise or operator (|), for example:

ocl::Image::builder().flags(ocl::MEM_WRITE_ONLY | ocl::MEM_COPY_HOST_PTR)...

Defaults to core::MEM_READ_WRITE if not set.

A slice use to designate a region of memory for use in combination of one of the two following flags:

  • flags::MEM_USE_HOST_PTR aka. MemFlags::new().use_host_ptr():

    • This flag is valid only if host_data is not None. If specified, it indicates that the application wants the OpenCL implementation to use memory referenced by host_data as the storage bits for the memory object (buffer/image).
    • OpenCL implementations are allowed to cache the buffer contents pointed to by host_data 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 buffer objects created with the same host_data or overlapping host regions is considered to be undefined.
    • Refer to the description of the alignment rules for host_data for memory objects (buffer and images) created using MEM_USE_HOST_PTR.
    • MEM_ALLOC_HOST_PTR and MEM_USE_HOST_PTR are mutually exclusive.

  • flags::MEM_COPY_HOST_PTR aka. MemFlags::new().copy_host_ptr()

    • This flag is valid only if host_data is not NULL. If specified, it indicates that the application wants the OpenCL implementation to allocate memory for the memory object and copy the data from memory referenced by host_data.
    • CL_MEM_COPY_HOST_PTR and CL_MEM_USE_HOST_PTR are mutually exclusive.
    • CL_MEM_COPY_HOST_PTR can be used with CL_MEM_ALLOC_HOST_PTR to initialize the contents of the cl_mem object allocated using host-accessible (e.g. PCIe) memory.

Note: Descriptions adapted from: https://www.khronos.org/registry/OpenCL/sdk/1.2/docs/man/xhtml/clCreateBuffer.html.

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.

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

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.

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.

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.

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.

Specifies the image pixel format.

If unspecified, defaults to:

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

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.

Deprecated since 0.13.0

: Use '::host_data' and '::build' instead.

Builds with the host side image data specified by host_data and returns a new Image.

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