Image Class#

Description

All oneIPL image processing functions operate with images. The oneIPL image defines 2D shared image data and supports ROI feature, extended format and Unified Shared Memory.

The oneIPL image class is a wrapper over memory - USM or image (texture). Type of the memory shall be specified by allocator template parameter. Library shall provide allocator types for USM allocation (host, shared, and device) and image (texture) allocation. Taking into account the restrictions of SYCL2020 standard, the image class using image memory must only be supported for oneapi::ipl::layouts::channel4 memory layout and restricted set of data types. For other layouts and types, the USM-based image class shall be used. Supported values for DataT if image is texture-based:

std::int8_t

std::uint8_t

std::int16_t

std::uint16_t

std::int32_t

std::uint32_t

float

Library shall provide type aliases to control memory allocation. USM memory can be allocated as host, device and shared. Type aliases shall work according to table below:

Allocator/Tag	Memory	Formats	Default Implementation	Object of class
host_allocator	Host Memory	All	usm_allocator (host)	image<…, host_allocator>
device_allocator	USM	All	Device allocator based on malloc_device	image<…, device_allocator>
shared_allocator	USM	All	usm_allocator (shared)	image<…, shared_allocator>
image_allocator	Image	Only 4-component, 8,16,32-bit	Image is allocated by runtime, image_allocator is allocator, which is used for host allocation only	image<…, image_allocator>

Image constructors from existing memory shall take pointers. Depending on what kind of pointer is provided memory shall be either allocated and copied or just mapped. The most efficient way is to void the copy operation and that shall be implemented as close to the table below as possible:

Pointer/Image	Host Image	Device Image	Shared Image	Image (Image memory)
Host pointer	Zero-copy	Copy	Copy	Copy
USM Device pointer	Copy	Zero-copy	Copy	Copy/Zero copy for some formats is possible
USM Shared pointer	Zero-copy	Zero-copy	Zero-copy	Copy/Zero copy for some formats is possible
Image	Copy/Zero copy for some formats is possible	Copy/Zero copy for some formats is possible	Copy/Zero copy for some formats is possible	Zero-copy

Include Files

oneapi/ipl.hpp

Domain Dependencies

Headers: oneapi/ipl.hpp

Libraries: oneipl.lib

Syntax

template<layouts Layout, typename DataT, typename AllocatorT = select_image_allocator_t<Layout, DataT>> class image#

Wrapper class for different image implementations (using image memory or USM).

Template Parameters

Layout – the given layout of an image
DataT – the given type of a pixel component
AllocatorT – the given type of an image allocator

Public Types

using data_t = DataT #: Alias for the type of a pixel component.

using allocator_t = AllocatorT #: Alias for the type of an image allocator.

Public Functions

explicit image(sycl::queue &queue, const sycl::range<2> &image_size)#

Constructor that allocates memory for an image of the given 2D size image_size.

Parameters

queue – [in] the given SYCL queue
image_size – [in] the given 2D size of an image

explicit image(const sycl::range<2> &image_size, AllocatorT allocator)#

Constructor that allocates memory for an image of the given 2D size image_size.

The given allocator allocator is used to allocate memory on host (if necessary).

Parameters

image_size – [in] the given 2D size of the image
allocator – [in] the allocator of the type AllocatorT

explicit image(sycl::queue &queue, const sycl::range<2> &image_size, std::size_t pitch)#

Constructor that allocates memory for an image of the given 2D size image_size using the given image stride pitch.

Parameters

queue – [in] the given SYCL queue
image_size – [in] the given 2D size of an image
pitch – [in] the given image stride in bytes

Throws

oneapi::ipl::invalid_argument – given pitch is too small

explicit image(const sycl::range<2> &image_size, std::size_t pitch, AllocatorT allocator)#

Constructor that allocates memory for an image of the given 2D size image_size using the given image stride pitch.

The given allocator allocator is used to allocate memory on host (if necessary).

Parameters

image_size – [in] the given 2D size of the image
pitch – [in] the given image stride in bytes
allocator – [in] the allocator of the type AllocatorT

Throws

oneapi::ipl::invalid_argument – given pitch is too small

explicit image(sycl::queue &queue, data_t *image_data, const sycl::range<2> &image_size, const std::vector<sycl::event> &dependencies = {})#

Constructor for a whole image of the given 2D size image_size that image data should be taken from memory by the given pointer image_data.

Parameters

queue – [in] the given SYCL queue
image_data – [in] the given pointer to the image data
image_size – [in] the given 2D size of the image
dependencies – [in] the dependencies that needed to wait until the image data image_data is ready

Throws

oneapi::ipl::invalid_argument – image_data is null

explicit image(sycl::queue &queue, data_t *image_data, const sycl::range<2> &image_size, AllocatorT allocator, const std::vector<sycl::event> &dependencies = {})#

Constructor for a whole image of the given 2D size image_size that image data should be taken from memory by the given pointer image_data.

The given allocator allocator is used to allocate memory on host (if necessary).

Parameters

queue – [in] the given SYCL queue
image_data – [in] the given pointer to the image data (it may be a USM pointer or a usual host pointer)
image_size – [in] the given 2D size of the image
allocator – [in] the allocator of the type AllocatorT
dependencies – [in] the dependencies that needed to wait until the image data image_data is ready

Throws

oneapi::ipl::invalid_argument – image_data is null

explicit image(sycl::queue &queue, data_t *image_data, const sycl::range<2> &image_size, std::size_t pitch, const std::vector<sycl::event> &dependencies = {})#

Constructor for a whole image of the given 2D size image_size with the given image stride pitch that image data should be taken from memory by the given pointer image_data.

Parameters

queue – [in] the given SYCL queue
image_data – [in] the given pointer to the image data
image_size – [in] the given 2D size of the image
pitch – [in] the given image stride in bytes
dependencies – [in] the dependencies that needed to wait until the image data image_data is ready

Throws

oneapi::ipl::invalid_argument – image_data is null
oneapi::ipl::invalid_argument – given pitch is too small

explicit image(sycl::queue &queue, data_t *image_data, const sycl::range<2> &image_size, std::size_t pitch, AllocatorT allocator, const std::vector<sycl::event> &dependencies = {})#

Constructor for a whole image of the given 2D size image_size with the given image stride pitch that image data should be taken from memory by the given pointer image_data.

The given allocator allocator is used to allocate memory on host (if necessary).

Parameters

queue – [in] the given SYCL queue
image_data – [in] the given pointer to the image data (it may be a USM pointer or a usual host pointer)
image_size – [in] the given 2D size of the image
pitch – [in] the given image stride in bytes
allocator – [in] the allocator of the type AllocatorT
dependencies – [in] the dependencies that needed to wait until the image data image_data is ready

Throws

oneapi::ipl::invalid_argument – image_data is null
oneapi::ipl::invalid_argument – given pitch is too small

explicit image(sycl::queue &queue, data_t *image_data, const sycl::range<2> &image_size, const roi_rect &roi_rect, const std::vector<sycl::event> &dependencies = {})#

Constructor for the ROI of the image specified by its bounding rectangle roi_rect.

The image data of the given 2D size image_size should be taken from memory by the given pointer image_data.

Parameters

queue – [in] the given SYCL queue
image_data – [in] the given pointer to the image data
image_size – [in] the given 2D size of the image
roi_rect – the given ROI rectangle
dependencies – [in] the dependencies that needed to wait until the image data image_data is ready

Throws

oneapi::ipl::invalid_argument – image_data is null
oneapi::ipl::invalid_argument – roi_rect doesn’t fit in image_size

explicit image(sycl::queue &queue, data_t *image_data, const sycl::range<2> &image_size, const roi_rect &roi_rect, AllocatorT allocator, const std::vector<sycl::event> &dependencies = {})#

Constructor for the ROI of the image specified by its bounding rectangle roi_rect.

The image data of the given 2D size image_size should be taken from memory by the given pointer image_data. The given allocator allocator is used to allocate memory on host (if necessary).

Parameters

queue – [in] the given SYCL queue
image_data – [in] the given pointer to the image data (it may be a USM pointer or a usual host pointer)
image_size – [in] the given 2D size of the image
roi_rect – the given ROI rectangle
allocator – [in] the allocator of the type AllocatorT
dependencies – [in] the dependencies that needed to wait until the image data image_data is ready

Throws

oneapi::ipl::invalid_argument – image_data is null
oneapi::ipl::invalid_argument – roi_rect doesn’t fit in image_size

explicit image(sycl::queue &queue, data_t *image_data, const sycl::range<2> &image_size, std::size_t pitch, const roi_rect &roi_rect, const std::vector<sycl::event> &dependencies = {})#

Constructor for the ROI of the image specified by its bounding rectangle roi_rect.

The image data of the given 2D size image_size with the given image stride pitch should be taken from memory by the given pointer image_data.

Parameters

queue – [in] the given SYCL queue
image_data – [in] the given pointer to the image data
image_size – [in] the given 2D size of the image
pitch – [in] the given image stride in bytes
roi_rect – the given ROI rectangle
dependencies – [in] the dependencies that needed to wait until the image data image_data is ready

Throws

oneapi::ipl::invalid_argument – image_data is null
oneapi::ipl::invalid_argument – given pitch is too small
oneapi::ipl::invalid_argument – roi_rect doesn’t fit in image_size

explicit image(sycl::queue &queue, data_t *image_data, const sycl::range<2> &image_size, std::size_t pitch, const roi_rect &roi_rect, AllocatorT allocator, const std::vector<sycl::event> &dependencies = {})#

Constructor for the ROI of the image specified by its bounding rectangle roi_rect.

The image data of the given 2D size image_size with the given image stride pitch should be taken from memory by the given pointer image_data. The given allocator allocator is used to allocate memory on host (if necessary).

Parameters

queue – [in] the given SYCL queue
image_data – [in] the given pointer to the image data (it may be a USM pointer or a usual host pointer)
image_size – [in] the given 2D size of the image
pitch – [in] the given image stride in bytes
roi_rect – the given ROI rectangle
allocator – [in] the allocator of the type AllocatorT
dependencies – [in] the dependencies that needed to wait until the image data image_data is ready

Throws

oneapi::ipl::invalid_argument – image_data is null
oneapi::ipl::invalid_argument – given pitch is too small
oneapi::ipl::invalid_argument – roi_rect doesn’t fit in image_size

explicit image(const image &image, const roi_rect &roi_rect)#

Constructor for the ROI of the given image image.

The ROI is specified by its bounding rectangle roi_rect.

Parameters

image – [in] the given image or ROI
roi_rect – the given ROI rectangle

Throws

oneapi::ipl::invalid_argument – roi_rect doesn’t fit in image_size

std::size_t get_pitch() const#

Returns the image stride in bytes.

Returns: the image stride in bytes

std::size_t get_size() const#

Returns the size of the ROI storage in bytes (for the whole image returns the size of the image storage).

Returns: the size of the ROI storage in bytes

AllocatorT get_allocator() const#

Returns the image allocator.

Returns: the image allocator

template<typename DestinationT = std::nullptr_t> void set_final_data(DestinationT final_data = nullptr)#

Sets where the output of all image processing will be copied to during destruction if the image was accessed by a write accessor.

Template Parameters: DestinationT – the given pointer type
Parameters: final_data – [in] the given pointer to store data

const roi_rect &get_rect() const noexcept#

Returns the bounding rectangle of the accessible data.

Returns: the bounding rectangle of the accessible data

auto get_origin() const -> image #

Returns the origin image (image for which ROI is defined, in case of image without ROI returns the shallow copy of the same image)

Returns: the origin image

auto get_roi(const roi_rect &roi_rect) const -> image #

Returns the ROI of this image specified by its bounding rectangle.

Parameters: roi_rect – the given ROI rectangle
Returns: the ROI of this image

template<typename AccessDataT, sycl::access_mode AccessMode> __unspecified__ get_access(sycl::handler &command_group_handler)#

Returns the device accessor for the data.

If ROI is specified, the accessible data is restricted by ROI and pixel coordinates are defined relative to ROI.

Template Parameters

AccessDataT – the given access type
AccessMode – the given access mode (sycl::access_mode)

Parameters

command_group_handler – [in] the given command group handler (an object of sycl::handler type)

Returns

the accessor for the image data, can be usm_image_accessor in case of USM or SYCL accessor in case of image data

template<typename AccessDataT, sycl::access_mode AccessMode> __unspecified__ get_access()#

Returns the host accessor for the data.

If ROI is specified, the accessible data is restricted by ROI and pixel coordinates are defined relative to ROI.

Template Parameters

AccessDataT – the given access type
AccessMode – the given access mode (sycl::access_mode)

Returns

the accessor for the image data, can be usm_image_accessor in case of USM or SYCL accessor in case of image data

Public Static Attributes

static constexpr auto layout_v = Layout #: Alias for the layout of an image.

static constexpr auto channel_count_v = detail::channel_count_v<Layout>#: Alias for the number of image channels.

Possible combinations for DataT and not Subsampled formats:

DataT/Layouts	plane	channel3	channel4	plane3
std::uint8_t	v	v	v	v
std::int8_t	v	v	v	v
std::uint16_t	v	v	v	v
std::int16_t	v	v	v	v
std::uint32_t	v	v	v	v
std::int32_t	v	v	v	v
float	v	v	v	v
double	v	v	v	v
half	v	v	v	v

Supported values for subsampled layout (only for std::uint8_t data type):

sub420	sub420i
v	v

Library shall provide subset of combinations supported by image class in each computational function.

The code example below demonstrates how shall be called oneapi::ipl::image with USM memory and ROI

using namespace oneapi;

sycl::queue                 queue;
ipl::shared_usm_allocator_t allocator{ queue };
const sycl::range<2>        image_size{ height, width };
const ipl::roi_rect         roi_rect{ image_size / 6, image_size / 3 };

// Source 3-channel image data
ipl::image<ipl::layouts::channel3, std::uint8_t> src_image{ queue, p_image_data, image_size, allocator };
// ROI of the source image
ipl::image<ipl::layouts::channel3, std::uint8_t> dst_image{ src_image, roi_rect };

oneIPL Specification documentation

Image Class

Image Class#