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 image classes using image memory or USM memory. The base image class may depend on the image format: the image class using image memory must only be used with oneapi::ipl::formats::rgba image format. For other formats, the USM-based image class shall be used.

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<formats Format, typename DataT, typename AllocatorT = select_image_allocator_t<Format, DataT>> class oneapi::ipl::image : public detail::image_impl_t<Format, DataT, select_image_allocator_t<Format, DataT>>¶

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

Template Parameters

Format – the given format of an image
DataT – the given type of a pixel component

Public Types

using allocator_t = AllocatorT ¶: Alias for image allocator.

using pixel_t = pixel_layout_t<DataT, Format>¶: Alias for image pixel type.

Public Functions

image(const image_impl_t &image_impl)¶

Converting copy constructor from the type of the used image implementation type.

Parameters: image_impl – [in] the given image implementation

image(image_impl_t &&image_impl)¶

Converting move constructor from the type of the used image implementation type.

Parameters: image_impl – [in] the given image implementation

auto operator=(const image_impl_t &image_impl) -> image&¶

Converting copy assignment operator from the type of the used image implementation type.

Parameters: image_impl – [in] the given image implementation
Returns: this image wrapper

auto operator=(image_impl_t &&image_impl) -> image&¶

Converting move assignment operator from the type of the used image implementation type.

Parameters: image_impl – [in] the given image implementation
Returns: this image wrapper

auto get_whole_image() const -> image ¶

Returns the wrapper for the whole image.

Returns: the wrapper for the whole image

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

Returns the wrapper for the ROI specified by the given ROI rectangle roi_rect.

Parameters: roi_rect – the given ROI rectangle
Returns: the wrapper for the ROI of the image

Possible combinations for DataT and not subsampled Formats:

DataT/Formats	plane	rgb/bgr	rgba/bgra	rgbp
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

Supported values for subsampled Format (only for DataT = std::uint8_t):

nv12	i420
v	v

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

The code example below demonstrates how to use the oneapi::ipl::image with USM memory and ROI

#include <oneapi/ipl.hpp>

using namespace oneapi::ipl;

const roi_rect roi_rect{ image_size / 6, image_size / 3 };

// Create queue
sycl::queue queue{};

// Create allocator
shared_usm_allocator_t allocator{ queue };

// RGB image (usm_image)
image<formats::rgb, std::uint8_t> usm_image{ queue, image_data_pointer, image_size, allocator };
// RGB image ROI (usm_image)
image<formats::rgb, std::uint8_t> usm_image_roi{ usm_image, roi_rect };

oneIPL Specification documentation

Image Class¶