USM Image Accessor#

Description

USM Image accessors provide access to USM images.

Include Files

oneapi/ipl.hpp

Domain Dependencies

Headers: oneapi/ipl.hpp

Libraries: oneipl.lib

Syntax

template<layouts Layout, typename DataT, sycl::access_mode AccessMode, typename AccessDataT>
class usm_image_accessor : public oneapi::ipl::usm_image_accessor_base<Layout, DataT, AccessMode>#

Provides access to a USM image.

Template Parameters:

  • Layout – the given layout of an image

  • DataT – the given type of a pixel component

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

  • AccessDataT – the given access type

Public Types

using data_t = typename usm_image_accessor_base_t::data_t#

Alias for the type of a pixel component.

template<typename SomeDataT>
using pixel_t = sycl::vec<SomeDataT, pixel_width_v>#

Alias for the pixel type.

template<typename SomeDataT>
using pixel4_t = sycl::vec<SomeDataT, sycl_channel_count_v>#

Alias for the 4-component pixel type corresponding to RGBA images.

using native_pixel_t = pixel_t<base_t>#

Alias for the pixel type with the given type of a pixel component.

using native_pixel4_t = pixel4_t<data_t>#

Alias for the 4-component pixel type corresponding to RGBA images with the given type of a pixel component.

using access_data_t = AccessDataT#

Alias for the type of a pixel component for computations.

using access_pixel_t = pixel_t<access_data_t>#

Alias for the pixel type with the type of a pixel component for computations.

using access_pixel4_t = pixel4_t<access_data_t>#

Alias for the 4-component pixel type corresponding to RGBA images with the type of a pixel component for computations.

Public Functions

auto read(const sycl::int2 &coordinates) const -> access_pixel4_t#

Reads and returns an element of the image at the coordinates specified by coordinates.

Parameters:

coordinates – [in] the given pixel coordinates

Returns:

an object of 4-component pixel type with the type of a pixel component for computations

template<sycl::access_mode AccessMode2 = access_mode_v>
void write(const sycl::int2 &coordinates, const access_pixel4_t &pixel) const#

Writes the value specified by pixel to the element of the image at the coordinates specified by coordinates.

Template Parameters:

AccessMode2 – the given access mode (sycl::access_mode)

Parameters:

  • coordinates – [in] the given pixel coordinates

  • pixel – [in] the given pixel

auto get_pointer() const noexcept -> qualified_data_t*#

Returns the const pointer to the accessed image pixel data.

Returns:

the const pointer to the pixel data

std::size_t get_count() const#

Returns the total number of pixels that this accessor may access.

Returns:

the total number of pixels that this accessor may access

sycl::range<2> get_range() const#

Returns a range object which represents the number of elements of DataT per dimension that this accessor may access.

Returns:

a range object which represents the number of elements of DataT per dimension that this accessor may access

std::size_t get_pitch() const noexcept#

Returns the image stride in bytes.

Returns:

the image stride in bytes

Public Static Attributes

static constexpr int sycl_channel_count_v = {}#

Alias for the number of channels corresponding to RGBA images.

static constexpr auto channel_count_v#

Alias for the number of image channels.

static constexpr auto pixel_width_v#

Alias for number of elements in a pixel.

Similar to channels except in the case of complex numbers where more elements are required to represent each channel

static constexpr auto access_mode_v#

Alias for the access mode.

static constexpr auto layout_v = Layout#

Alias for the layout of an image.

static constexpr auto is_access_read_only_v = detail::is_access_read_only(AccessMode)#

The flag that shows whether the access mode is read-only.

static constexpr auto is_access_any_write_v = detail::is_access_any_write(AccessMode)#

The flag that shows whether the access mode is any write.

Supported values for AccessMode:

sycl::access_mode::write

sycl::access_mode::read

Supported values for AccessDataT:

std::int8_t

std::uint8_t

std::int16_t

std::uint16_t

std::int32_t

std::uint32_t

float

The code example below demonstrates how oneapi::ipl::usm_image_accessor shall be created and used:

using namespace oneapi;

sycl::queue                 queue;
ipl::shared_usm_allocator_t allocator{ queue };
const sycl::range<2>        image_size{ height, width };
const sycl::int2            coords2d{ 0, 0 };

// 3-channel image
ipl::image<ipl::layouts::channel3, std::uint8_t> usm_image{ queue, p_image_data, image_size, allocator };

// USM image accessor
const auto usm_image_accessor = usm_image.get_access<sycl::vec<float, 4>, sycl::access_mode::read>();

// Reading first pixel
const auto pixel = usm_image_accessor.read(coords2d);

std::cout << "Pixel: " << pixel[0] << " " << pixel[1] << " " << pixel[2] << std::endl;