Image_Image Class

Description

The image_image class is an image implementation using image memory with ROI support. It must be the base class for the Image class with oneapi::ipl::formats::rgba format. 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 AllocatorT>
class oneapi::ipl::image_image

Image implementation using image memory.

Template Parameters

  • Format – the given format 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.

Public Functions

explicit image_image(const sycl::range<2> &image_size)

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

Parameters

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

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

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

Parameters

  • 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_image(const sycl::range<2> &image_size, AllocatorT allocator)

Constructor that allocates 2D image 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_image(const sycl::range<2> &image_size, std::size_t pitch, AllocatorT allocator)

Constructor that allocates 2D image 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_image(data_t *image_data, const sycl::range<2> &image_size)

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

  • image_data – [in] the given pointer to the image data

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

Throws

oneapi::ipl::invalid_argument – image_data is null

explicit image_image(data_t *image_data, const sycl::range<2> &image_size, std::size_t pitch)

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

  • 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

Throws

  • oneapi::ipl::invalid_argument – image_data is null

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

explicit image_image(data_t *image_data, const sycl::range<2> &image_size, AllocatorT allocator)

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

  • image_data – [in] the given pointer to the image data

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

  • allocator – [in] the allocator of the type AllocatorT

Throws

oneapi::ipl::invalid_argument – image_data is null

explicit image_image(data_t *image_data, const sycl::range<2> &image_size, std::size_t pitch, AllocatorT allocator)

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

  • 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

  • allocator – [in] the allocator of the type AllocatorT

Throws

  • oneapi::ipl::invalid_argument – image_data is null

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

explicit image_image(sycl::queue &queue, data_t *image_data, const sycl::range<2> &image_size, AllocatorT allocator)

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). Alignment with usm_image class, queue parameter is not used.

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

Throws

oneapi::ipl::invalid_argument – image_data is null

explicit image_image(sycl::queue &queue, data_t *image_data, const sycl::range<2> &image_size, std::size_t pitch, AllocatorT allocator)

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). Alignment with usm_image class, queue parameter is not used.

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

Throws

  • oneapi::ipl::invalid_argument – image_data is null

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

explicit image_image(data_t *image_data, const sycl::range<2> &image_size, const roi_rect &roi_rect)

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

  • 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

Throws

  • oneapi::ipl::invalid_argument – image_data is null

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

explicit image_image(data_t *image_data, const sycl::range<2> &image_size, std::size_t pitch, const roi_rect &roi_rect)

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

  • 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

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_image(data_t *image_data, const sycl::range<2> &image_size, const roi_rect &roi_rect, AllocatorT allocator)

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

  • 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

  • allocator – [in] the allocator of the type AllocatorT

Throws

  • oneapi::ipl::invalid_argument – image_data is null

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

explicit image_image(data_t *image_data, const sycl::range<2> &image_size, std::size_t pitch, const roi_rect &roi_rect, AllocatorT allocator)

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

  • 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

  • allocator – [in] the allocator of the type AllocatorT

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_image(sycl::queue &queue, data_t *image_data, const sycl::range<2> &image_size, const roi_rect &roi_rect, AllocatorT allocator)

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). Alignment with usm_image class, queue parameter is not used.

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

Throws

  • oneapi::ipl::invalid_argument – image_data is null

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

explicit image_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)

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). Alignment with usm_image class, queue parameter is not used.

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

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_image(const image_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

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

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

sycl::range<2> get_whole_image_range() const

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 -> image_image

Returns the whole image.

Returns

the whole image

auto get_roi(const roi_rect &roi_rect) const -> image_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

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.

Supported values for Format:

rgba

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 Class

next

USM_Image Class