USM_Image Class

Description

The usm_image class provides functionality similar to oneapi::ipl::image_image class based on Unified Shared Memory with extended format and ROI support. It must be the base class for the Image class if format is not oneapi::ipl::formats::rgba. This class is not recommended for use as a parameter in oneIPL image processing functions, use Image class instead.

Include Files

oneapi/ipl.hpp

Domain Dependencies

Headers: oneapi/ipl.hpp

Libraries: oneipl.lib

Syntax

template<formats Format, typename DataT, typename UsmAllocatorT>
class oneapi::ipl::usm_image

Image implementation using unified shared memory (USM).

Template Parameters

  • Format – the given format of an image

  • DataT – the given type of a pixel component

  • UsmAllocatorT – the given type of an USM allocator

Public Types

using data_t = DataT

Alias for the type of a pixel component.

template<sycl::access_mode AccessMode, typename AccessDataT>
using accessor_t = usm_image_accessor<Format, data_t, AccessMode, AccessDataT>

Alias template for the USM image accessor.

Template Parameters

  • AccessMode – the given access mode (sycl::access_mode)

  • AccessDataT – the given access type

Public Functions

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

Constructor for the whole image.

Uses the given pointer to the image data image_data if it is a USM pointer in the SYCL context associated with the given SYCL queue queue and has the same allocation kind as the USM allocator UsmAllocatorT, or allocates a USM pointer using the given USM allocator usm_allocator and asynchronously copies the image data from image_data to it.

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

  • usm_allocator – [in] the USM allocator of the type UsmAllocatorT that is used to allocate USM for the image data

  • 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 usm_image(sycl::queue &queue, data_t *image_data, const sycl::range<2> &image_size, std::size_t pitch, const UsmAllocatorT &usm_allocator, const std::vector<sycl::event> &dependencies = {})

Constructor for the whole image.

Uses the given pointer to the image data image_data if it is a USM pointer in the SYCL context associated with the given SYCL queue queue and has the same allocation kind as the USM allocator UsmAllocatorT, or allocates a USM pointer using the given USM allocator usm_allocator and asynchronously copies the image data from image_data to it.

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

  • usm_allocator – [in] the USM allocator of the type UsmAllocatorT that is used to allocate USM for the image data

  • 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 usm_image(const sycl::range<2> &image_size, const UsmAllocatorT &usm_allocator)

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

Parameters

  • image_size – [in] the given 2D size of the image

  • usm_allocator – [in] the USM allocator of the type UsmAllocatorT that is used to allocate USM for the image data

explicit usm_image(const sycl::range<2> &image_size, std::size_t pitch, const UsmAllocatorT &usm_allocator)

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

Parameters

  • image_size – [in] the given 2D size of the image

  • pitch – [in] the given image stride in bytes

  • usm_allocator – [in] the USM allocator of the type UsmAllocatorT that is used to allocate USM for the image data

Throws

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

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

Constructor for the ROI of the given image image.

The ROI is specified by its bounding rectangle.

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

const sycl::range<2> &get_range() const noexcept

Returns the range of the ROI (for the whole image returns the range of the image).

Returns

the range of the ROI

std::size_t get_pitch() const

Returns the image stride in bytes.

Returns

the image stride in bytes

std::size_t get_count() const

Returns the total number of pixels in the ROI (for the whole image returns the total number in the image).

Returns

the total number of pixels in the ROI

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

const UsmAllocatorT &get_allocator() const

Returns the USM allocator.

Returns

the USM 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 sycl::range<2> &get_whole_image_range() const noexcept

Returns the 2D size of the whole image.

Returns

the 2D size of the whole image

std::size_t get_whole_image_width() const

Returns the width of the whole image.

Returns

the width of the whole image

std::size_t get_whole_image_height() const

Returns the height of the whole image.

Returns

the height of the whole image

const roi_rect &get_roi_rect() const noexcept

Returns the bounding rectangle of the ROI (for the whole image the offset is (0, 0), and the size is equal to the size of the image).

Returns

the bounding rectangle of the ROI

const sycl::id<2> &get_offset() const noexcept

Returns the offset of the ROI (for the whole image returns (0, 0)).

Returns

the offset of the ROI

bool is_roi() const

Checks whether this object represents the ROI of the image.

Returns

true if this object represents the ROI of the image, or false if it represents the whole image

auto get_whole_image() const -> usm_image

Returns the whole image.

Returns

the whole image

auto get_roi(const roi_rect &roi_rect) const -> usm_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>
auto get_access(sycl::handler &command_group_handler) -> accessor_t<AccessMode, typename AccessDataT::element_type>

Returns the USM image accessor for this USM image.

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 USM image accessor for this USM image

template<typename AccessDataT, sycl::access_mode AccessMode>
auto get_access() -> accessor_t<AccessMode, typename AccessDataT::element_type>

Returns the USM image accessor for this USM image.

Template Parameters

  • AccessDataT – the given access type

  • AccessMode – the given access mode (sycl::access_mode)

Returns

the USM image accessor for this USM image

Public Static Attributes

static constexpr auto format_v = Format

Alias for the format of an image.

static constexpr auto channel_count_v = detail::channel_count_v<Format>

Alias for the number of image channels.

static constexpr auto alloc_kind_v = usm_alloc_kind_v<UsmAllocatorT>

USM allocation kind.

Supported values for Format:

rgb

bgr

bgra

nv12

i420

plane

rgbp

Supported values for DataT:

std::int8_t

std::uint8_t

std::int16_t

std::uint16_t

std::int32_t

std::uint32_t

float

previous

Image_Image Class

next

Image Borders