Image Class#

Description

All oneIPL functions operate on image data. The oneIPL image defines 2D shared image data supporting an image ROI, extended format, and unified shared memory (USM).

The oneIPL image class is a wrapper over USM or image (texture or sycl::image) memory. The type of the memory is specified by the allocator template parameter. oneIPL provides allocator types for USM (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 the oneapi::ipl::layouts::channel4 memory layout and restricted set of data types. For other layouts and types, the USM-based image class is used.

The following standard types are the supported values for DataT for texture-based images:

std::int8_t

std::int16_t

std::int32_t

float

std::uint8_t

std::uint16_t

std::uint32_t

The library provides type aliases to control memory allocation. USM can be allocated as host, device, or shared memory. Type aliases work according to the following table:

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 take pointers. Depending on the pointer provided, memory is either allocated and copied or mapped. Zero copies are most efficient way and are implemented when possible according to the table below:

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

✓

✓

✓

✓

std::int8_t

✓

✓

✓

✓

std::uint16_t

✓

✓

✓

✓

std::int16_t

✓

✓

✓

✓

std::uint32_t

✓

✓

✓

✓

std::int32_t

✓

✓

✓

✓

float

✓

✓

✓

✓

double

✓

✓

✓

✓

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

sub420

sub420i

✓

✓

Each library function supports a subset of the image class.

The code example below demonstrates how oneapi::ipl::image is called with USM memory and an 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 };