Struct ocl::builders::ImageBuilder
source · pub struct ImageBuilder<'a, T>where
T: 'a,{ /* private fields */ }
Expand description
A builder for Image
.
Implementations§
source§impl<'a, T> ImageBuilder<'a, T>where
T: 'a + OclPrm,
impl<'a, T> ImageBuilder<'a, T>where
T: 'a + OclPrm,
sourcepub fn new() -> ImageBuilder<'a, T>
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.
sourcepub fn context<'o>(self, context: &'o Context) -> ImageBuilder<'a, T>where
'o: 'a,
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).
sourcepub fn queue<'b>(self, default_queue: Queue) -> ImageBuilder<'a, T>
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).
sourcepub fn flags(self, flags: MemFlags) -> ImageBuilder<'a, T>
pub fn flags(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.
sourcepub unsafe fn use_host_slice<'d>(
self,
host_slice: &'d [T]
) -> ImageBuilder<'a, T>where
'd: 'a,
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.
sourcepub fn copy_host_slice<'d>(self, host_slice: &'d [T]) -> ImageBuilder<'a, T>where
'd: 'a,
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>
sourcepub fn image_type(self, image_type: MemObjectType) -> 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
.
sourcepub fn dims<D>(self, dims: D) -> ImageBuilder<'a, T>where
D: Into<SpatialDims>,
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)
.
sourcepub fn array_size(self, array_size: usize) -> ImageBuilder<'a, T>
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.
sourcepub fn row_pitch_bytes(self, row_pitch: usize) -> ImageBuilder<'a, T>
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.
sourcepub fn slc_pitch_bytes(self, slc_pitch: usize) -> ImageBuilder<'a, T>
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.
sourcepub fn buffer_sync(self, buffer: MemCore) -> ImageBuilder<'a, T>
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.
sourcepub fn image_format(self, image_format: ImageFormat) -> ImageBuilder<'a, T>
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,
}
sourcepub unsafe fn image_desc(
self,
image_desc: ImageDescriptor
) -> ImageBuilder<'a, T>
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.