Batch Class#

Description

Some oneIPL image processing functions operate with batches of images. A batch defines the set of 2D images and image ROI, extended format, and unified shared memory.

The oneIPL batch class is a wrapper over USM pointers to image data descriptors of oneapi::ipl::image_descriptor type. The batch class does not provide memory allocation. The user is responsible for providing valid USM pointers accessible on the device where they will be used.

Include Files

oneapi/ipl.hpp

Domain Dependencies

Headers: oneapi/ipl.hpp

Libraries: oneipl.lib

Syntax

template<layouts Layout, typename DataT> class batch#

Class for batch representation.

Template Parameters:

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

Public Types

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

using pixel_t = pixel_layout_t<DataT, Layout>#: Alias for image pixel type.

Public Functions

batch(image_descriptor<Layout, DataT> *const image_descriptors, const std::size_t batch_size, const sycl::range<2> &first_roi_size)#

Constructor of batch from pointer to image descriptors.

Parameters:

image_descriptors – [in] pointer to image_descriptor objects
batch_size – [in] number of images in batch
first_roi_size – [in] ROI size of images in batch; in case of different ROI sizes, ROI size of the first image

image_descriptor<Layout, DataT> *get_image_descriptors() noexcept#

Returns the pointer to the image descriptors.

Returns:: the pointer to the image descriptors

const sycl::range<3> &get_range() const noexcept#

Returns 3D range of the batch in format sycl::range<3>{ batch_size, height, width }.

Returns:: 3D range of the batch in format sycl::range<3>{ batch_size, height, width }

Public Static Attributes

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

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

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	✓	✓	✓	✓
half	✓	✓	✓	✓

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

sub420	sub420i
✓	✓

Library shall provide a subset of image type and layout combinations supported by batch class which is specified in each computational function specification for batch processing.

The code example below demonstrates how a oneapi::ipl::batch is constructed from a vector of image descriptors:

using namespace oneapi;

sycl::queue queue;
std::size_t batch_size{ 10U };
std::size_t num_channels{ 3U };
auto        image_descriptors{ sycl::malloc_shared<ipl::image_descriptor<ipl::layouts::channel3, std::uint8_t>>(queue, batch_size) };

// ptrs, pitches, sizes, rois - the arrays describing images in the batches, shall be filled by data before assigning to image decriptors
const sycl::range<2> img_size{ src_image_data.get_range() };
const auto pitch { img_size[1] * num_channels };

for (std::size_t i{ 0U }; i < batch_size; ++i) {
  // Allocate GPU memory for input image
  std::uint8_t* ptr = sycl::malloc_shared<std::uint8_t>(img_size[0] * img_size[1] * num_channels, queue);
  image_descriptors[i] = { ptr, pitch, img_size, img_size };
}

// 3-channel batch data
ipl::batch<ipl::layouts::channel3, std::uint8_t> batch{ image_descriptors, batch_size, img_size };