# 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]

#### `pub fn new() -> ImageBuilder<'a, T>`
[src]

Returns a new `ImageBuilder` with very basic defaults.

## Defaults

- Flags:

ⓘThis example is not tested

    ocl::MEM_READ_WRITE

- Image Format:

ⓘThis example is not tested

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

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

ⓘThis example is not tested

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

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>`
[src]

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>`
[src]

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

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

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>`
[src]

#### `pub fn channel_data_type(
self,
data_type: ImageChannelDataType
) -> ImageBuilder<'a, T>`
[src]

#### `pub fn image_type(self, image_type: MemObjectType) -> ImageBuilder<'a, T>`
[src]

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

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>`
[src]

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>`
[src]

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>`
[src]

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>`
[src]

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>`
[src]

Specifies the image pixel format.

If unspecified, defaults to:

ⓘThis example is not tested

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

#### `pub unsafe fn image_desc(
self,
image_desc: ImageDescriptor
) -> ImageBuilder<'a, T>`
[src]

Specifies the image descriptor containing a number of important settings.

If unspecified (not recommended), defaults to:

ⓘThis example is not tested

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

ⓘThis example is not tested

    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>>`
[src]

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

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)