DPC++ Runtime
Runtime libraries for oneAPI DPC++
image.hpp
Go to the documentation of this file.
1 //==------------ image.hpp -------------------------------------------------==//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
9 #pragma once
10 
12 #include <sycl/detail/common.hpp>
15 #include <sycl/event.hpp>
17 #include <sycl/stl.hpp>
18 #include <sycl/types.hpp>
19 
20 #include <cstddef>
21 
22 namespace sycl {
24 
25 class handler;
26 
27 enum class image_channel_order : unsigned int {
28  a = 0,
29  r = 1,
30  rx = 2,
31  rg = 3,
32  rgx = 4,
33  ra = 5,
34  rgb = 6,
35  rgbx = 7,
36  rgba = 8,
37  argb = 9,
38  bgra = 10,
39  intensity = 11,
40  luminance = 12,
41  abgr = 13,
42  ext_oneapi_srgba = 14 // OpenCL 2.0
43 };
44 
45 enum class image_channel_type : unsigned int {
46  snorm_int8 = 0,
47  snorm_int16 = 1,
48  unorm_int8 = 2,
49  unorm_int16 = 3,
50  unorm_short_565 = 4,
51  unorm_short_555 = 5,
52  unorm_int_101010 = 6,
53  signed_int8 = 7,
54  signed_int16 = 8,
55  signed_int32 = 9,
56  unsigned_int8 = 10,
57  unsigned_int16 = 11,
58  unsigned_int32 = 12,
59  fp16 = 13,
60  fp32 = 14
61 };
62 
63 using byte = unsigned char;
64 
66 
67 namespace detail {
68 
69 class image_impl;
70 
71 // validImageDataT: cl_int4, cl_uint4, cl_float4, cl_half4
72 template <typename T>
75 
76 template <typename DataT>
79 
80 // The non-template base for the sycl::image class
81 class __SYCL_EXPORT image_plain {
82 protected:
84  const range<3> &Range,
85  std::unique_ptr<SYCLMemObjAllocator> Allocator,
86  uint8_t Dimensions, const property_list &PropList);
87 
89  const range<3> &Range, const range<2> &Pitch,
90  std::unique_ptr<SYCLMemObjAllocator> Allocator,
91  uint8_t Dimensions, const property_list &PropList);
92 
93  image_plain(void *HostPointer, image_channel_order Order,
94  image_channel_type Type, const range<3> &Range,
95  std::unique_ptr<SYCLMemObjAllocator> Allocator,
96  uint8_t Dimensions, const property_list &PropList);
97 
98  image_plain(const void *HostPointer, image_channel_order Order,
99  image_channel_type Type, const range<3> &Range,
100  std::unique_ptr<SYCLMemObjAllocator> Allocator,
101  uint8_t Dimensions, const property_list &PropList);
102 
103  image_plain(void *HostPointer, image_channel_order Order,
104  image_channel_type Type, const range<3> &Range,
105  const range<2> &Pitch,
106  std::unique_ptr<SYCLMemObjAllocator> Allocator,
107  uint8_t Dimensions, const property_list &PropList);
108 
109  image_plain(const std::shared_ptr<const void> &HostPointer,
111  const range<3> &Range,
112  std::unique_ptr<SYCLMemObjAllocator> Allocator,
113  uint8_t Dimensions, const property_list &PropList,
114  bool IsConstPtr);
115 
116  image_plain(const std::shared_ptr<const void> &HostPointer,
118  const range<3> &Range, const range<2> &Pitch,
119  std::unique_ptr<SYCLMemObjAllocator> Allocator,
120  uint8_t Dimensions, const property_list &PropList,
121  bool IsConstPtr);
122 
123 #ifdef __SYCL_INTERNAL_API
124  image_plain(cl_mem ClMemObject, const context &SyclContext,
125  event AvailableEvent,
126  std::unique_ptr<SYCLMemObjAllocator> Allocator,
127  uint8_t Dimensions);
128 #endif
129 
130  template <typename propertyT> bool has_property() const noexcept;
131 
132  template <typename propertyT> propertyT get_property() const;
133 
134  range<3> get_range() const;
135 
136  range<2> get_pitch() const;
137 
138  size_t get_size() const;
139 
140  size_t get_count() const;
141 
142  void set_final_data_internal();
143 
144  void set_final_data_internal(
145  const std::function<void(const std::function<void(void *const Ptr)> &)>
146  &FinalDataFunc);
147 
148  void set_write_back(bool flag);
149 
150  const std::unique_ptr<SYCLMemObjAllocator> &get_allocator_internal() const;
151 
152  size_t getElementSize() const;
153 
154  size_t getRowPitch() const;
155 
156  size_t getSlicePitch() const;
157 
158  image_channel_order getChannelOrder() const;
159 
160  image_channel_type getChannelType() const;
161 
162  std::shared_ptr<detail::image_impl> impl;
163 };
164 
165 template <typename DataT, int Dims, access::mode AccMode,
166  access::target AccTarget, access::placeholder IsPlaceholder>
167 class image_accessor;
168 
169 } // namespace detail
170 
180 template <int Dimensions = 1, typename AllocatorT = sycl::image_allocator>
181 class image : public detail::image_plain {
182 
183 public:
185  const range<Dimensions> &Range, const property_list &PropList = {})
186  : image_plain(Order, Type, detail::convertToArrayOfN<3, 1>(Range),
189  Dimensions, PropList) {}
190 
192  const range<Dimensions> &Range, AllocatorT Allocator,
193  const property_list &PropList = {})
194  : image_plain(
195  Order, Type, detail::convertToArrayOfN<3, 1>(Range),
198  Dimensions, PropList) {}
199 
200  /* Available only when: dimensions >1 */
201  template <bool B = (Dimensions > 1)>
203  const range<Dimensions> &Range,
204  const typename detail::enable_if_t<B, range<Dimensions - 1>> &Pitch,
205  const property_list &PropList = {})
206  : image_plain(Order, Type, detail::convertToArrayOfN<3, 1>(Range),
207  detail::convertToArrayOfN<2, 0>(Pitch),
210  Dimensions, PropList) {}
211 
212  /* Available only when: dimensions >1 */
213  template <bool B = (Dimensions > 1)>
215  const range<Dimensions> &Range,
216  const typename detail::enable_if_t<B, range<Dimensions - 1>> &Pitch,
217  AllocatorT Allocator, const property_list &PropList = {})
218  : image_plain(
219  Order, Type, detail::convertToArrayOfN<3, 1>(Range),
220  detail::convertToArrayOfN<2, 0>(Pitch),
223  Dimensions, PropList) {}
224 
225  image(void *HostPointer, image_channel_order Order, image_channel_type Type,
226  const range<Dimensions> &Range, const property_list &PropList = {})
227  : image_plain(HostPointer, Order, Type,
228  detail::convertToArrayOfN<3, 1>(Range),
231  Dimensions, PropList) {}
232 
233  image(void *HostPointer, image_channel_order Order, image_channel_type Type,
234  const range<Dimensions> &Range, AllocatorT Allocator,
235  const property_list &PropList = {})
236  : image_plain(
237  HostPointer, Order, Type, detail::convertToArrayOfN<3, 1>(Range),
240  Dimensions, PropList) {}
241 
242  image(const void *HostPointer, image_channel_order Order,
243  image_channel_type Type, const range<Dimensions> &Range,
244  const property_list &PropList = {})
245  : image_plain(HostPointer, Order, Type,
246  detail::convertToArrayOfN<3, 1>(Range),
249  Dimensions, PropList) {}
250 
251  image(const void *HostPointer, image_channel_order Order,
252  image_channel_type Type, const range<Dimensions> &Range,
253  AllocatorT Allocator, const property_list &PropList = {})
254  : image_plain(
255  HostPointer, Order, Type, detail::convertToArrayOfN<3, 1>(Range),
258  Dimensions, PropList) {}
259 
260  /* Available only when: dimensions >1 */
261  template <bool B = (Dimensions > 1)>
262  image(void *HostPointer, image_channel_order Order, image_channel_type Type,
263  const range<Dimensions> &Range,
264  const typename detail::enable_if_t<B, range<Dimensions - 1>> &Pitch,
265  const property_list &PropList = {})
266  : image_plain(HostPointer, Order, Type,
267  detail::convertToArrayOfN<3, 1>(Range),
268  detail::convertToArrayOfN<2, 0>(Pitch),
271  Dimensions, PropList) {}
272 
273  /* Available only when: dimensions >1 */
274  template <bool B = (Dimensions > 1)>
275  image(void *HostPointer, image_channel_order Order, image_channel_type Type,
276  const range<Dimensions> &Range,
277  const typename detail::enable_if_t<B, range<Dimensions - 1>> &Pitch,
278  AllocatorT Allocator, const property_list &PropList = {})
279  : image_plain(
280  HostPointer, Order, Type, detail::convertToArrayOfN<3, 1>(Range),
281  detail::convertToArrayOfN<2, 0>(Pitch),
284  Dimensions, PropList) {}
285 
286  image(std::shared_ptr<void> &HostPointer, image_channel_order Order,
287  image_channel_type Type, const range<Dimensions> &Range,
288  const property_list &PropList = {})
289  : image_plain(HostPointer, Order, Type,
290  detail::convertToArrayOfN<3, 1>(Range),
293  Dimensions, PropList, /*IsConstPtr*/ false) {}
294 
295  image(std::shared_ptr<void> &HostPointer, image_channel_order Order,
296  image_channel_type Type, const range<Dimensions> &Range,
297  AllocatorT Allocator, const property_list &PropList = {})
298  : image_plain(
299  HostPointer, Order, Type, detail::convertToArrayOfN<3, 1>(Range),
302  Dimensions, PropList, /*IsConstPtr*/ false) {}
303 
304  /* Available only when: dimensions >1 */
305  template <bool B = (Dimensions > 1)>
306  image(std::shared_ptr<void> &HostPointer, image_channel_order Order,
307  image_channel_type Type, const range<Dimensions> &Range,
308  const typename detail::enable_if_t<B, range<Dimensions - 1>> &Pitch,
309  const property_list &PropList = {})
310  : image_plain(HostPointer, Order, Type,
311  detail::convertToArrayOfN<3, 1>(Range),
312  detail::convertToArrayOfN<2, 0>(Pitch),
315  Dimensions, PropList, /*IsConstPtr*/ false) {}
316 
317  /* Available only when: dimensions >1 */
318  template <bool B = (Dimensions > 1)>
319  image(std::shared_ptr<void> &HostPointer, image_channel_order Order,
320  image_channel_type Type, const range<Dimensions> &Range,
321  const typename detail::enable_if_t<B, range<Dimensions - 1>> &Pitch,
322  AllocatorT Allocator, const property_list &PropList = {})
323  : image_plain(
324  HostPointer, Order, Type, detail::convertToArrayOfN<3, 1>(Range),
325  detail::convertToArrayOfN<2, 0>(Pitch),
328  Dimensions, PropList, /*IsConstPtr*/ false) {}
329 
330 #ifdef __SYCL_INTERNAL_API
331  image(cl_mem ClMemObject, const context &SyclContext,
332  event AvailableEvent = {})
333  : image_plain(ClMemObject, SyclContext, AvailableEvent,
335  detail::SYCLMemObjAllocatorHolder<AllocatorT, byte>>(),
336  Dimensions) {}
337 #endif
338 
339  /* -- common interface members -- */
340 
341  image(const image &rhs) = default;
342 
343  image(image &&rhs) = default;
344 
345  image &operator=(const image &rhs) = default;
346 
347  image &operator=(image &&rhs) = default;
348 
349  ~image() = default;
350 
351  bool operator==(const image &rhs) const { return impl == rhs.impl; }
352 
353  bool operator!=(const image &rhs) const { return !(*this == rhs); }
354 
355  /* -- property interface members -- */
356  template <typename propertyT> bool has_property() const noexcept {
357  return image_plain::template has_property<propertyT>();
358  }
359 
360  template <typename propertyT> propertyT get_property() const {
361  return image_plain::get_property<propertyT>();
362  }
363 
365  return detail::convertToArrayOfN<Dimensions, 0>(image_plain::get_range());
366  }
367 
368  /* Available only when: dimensions >1 */
369  template <bool B = (Dimensions > 1)>
371  return detail::convertToArrayOfN<Dimensions - 1, 0>(
372  image_plain::get_pitch());
373  }
374 
375  // Returns the size of the image storage in bytes
376  size_t get_size() const { return image_plain::get_size(); }
377 
378  // Returns the total number of elements in the image
379  __SYCL2020_DEPRECATED("get_count() is deprecated, please use size() instead")
380  size_t get_count() const { return size(); }
381  size_t size() const noexcept { return image_plain::get_count(); }
382 
383  // Returns the allocator provided to the image
384  AllocatorT get_allocator() const {
385  return image_plain::get_allocator_internal()
386  ->template getAllocator<AllocatorT>();
387  }
388 
389  template <typename DataT, access::mode AccessMode>
391  access::target::image, access::placeholder::false_t,
393  get_access(handler &commandGroupHandler) {
394  return accessor<DataT, Dimensions, AccessMode, access::target::image,
395  access::placeholder::false_t,
397  commandGroupHandler);
398  }
399 
400  template <typename DataT, access::mode AccessMode>
402  access::target::host_image, access::placeholder::false_t,
405  return accessor<DataT, Dimensions, AccessMode, access::target::host_image,
406  access::placeholder::false_t,
408  }
409 
410  template <typename Destination = std::nullptr_t>
411  void set_final_data(Destination finalData = nullptr) {
412  this->set_final_data_internal(finalData);
413  }
414 
415  void set_final_data_internal(std::nullptr_t) {
416  image_plain::set_final_data_internal();
417  }
418 
419  template <template <typename WeakT> class WeakPtrT, typename WeakT>
421  std::is_convertible<WeakPtrT<WeakT>, std::weak_ptr<WeakT>>::value>
422  set_final_data_internal(WeakPtrT<WeakT> FinalData) {
423  std::weak_ptr<WeakT> TempFinalData(FinalData);
424  this->set_final_data_internal(TempFinalData);
425  }
426 
427  template <typename WeakT>
428  void set_final_data_internal(std::weak_ptr<WeakT> FinalData) {
429  image_plain::set_final_data_internal(
430  [FinalData](const std::function<void(void *const Ptr)> &F) {
431  if (std::shared_ptr<WeakT> LockedFinalData = FinalData.lock())
432  F(LockedFinalData.get());
433  });
434  }
435 
436  template <typename Destination>
438  set_final_data_internal(Destination FinalData) {
439  if (!FinalData)
440  image_plain::set_final_data_internal();
441  else
442  image_plain::set_final_data_internal(
443  [FinalData](const std::function<void(void *const Ptr)> &F) {
444  F(FinalData);
445  });
446  }
447 
448  template <typename Destination>
450  set_final_data_internal(Destination FinalData) {
451  const size_t Size = size();
452  image_plain::set_final_data_internal(
453  [FinalData, Size](const std::function<void(void *const Ptr)> &F) {
454  using DestinationValueT = detail::iterator_value_type_t<Destination>;
455  // TODO if Destination is ContiguousIterator then don't create
456  // ContiguousStorage. updateHostMemory works only with pointer to
457  // continuous data.
458  std::unique_ptr<DestinationValueT[]> ContiguousStorage(
459  new DestinationValueT[Size]);
460  F(ContiguousStorage.get());
461  std::copy(ContiguousStorage.get(), ContiguousStorage.get() + Size,
462  FinalData);
463  });
464  }
465 
466  void set_write_back(bool flag = true) { image_plain::set_write_back(flag); }
467 
468 private:
469  // This utility api is currently used by accessor to get the element size of
470  // the image. Element size is dependent on num of channels and channel type.
471  // This information is not accessible from the image using any public API.
472  size_t getElementSize() const { return image_plain::getElementSize(); }
473 
474  size_t getRowPitch() const { return image_plain::getRowPitch(); }
475 
476  size_t getSlicePitch() const { return image_plain::getSlicePitch(); }
477 
478  image_channel_order getChannelOrder() const {
479  return image_plain::getChannelOrder();
480  }
481 
482  image_channel_type getChannelType() const {
483  return image_plain::getChannelType();
484  }
485 
486  template <class Obj>
487  friend decltype(Obj::impl) detail::getSyclObjImpl(const Obj &SyclObject);
488 
489  template <typename DataT, int Dims, access::mode AccMode,
491  typename PropertyListT>
492  friend class accessor;
493 
494  template <typename DataT, int Dims, access::mode AccMode,
497 };
498 
499 } // __SYCL_INLINE_VER_NAMESPACE(_V1)
500 } // namespace sycl
501 
502 namespace std {
503 template <int Dimensions, typename AllocatorT>
504 struct hash<sycl::image<Dimensions, AllocatorT>> {
505  size_t operator()(const sycl::image<Dimensions, AllocatorT> &I) const {
506  return hash<std::shared_ptr<sycl::detail::image_impl>>()(
508  }
509 };
510 } // namespace std
The context class represents a SYCL context on which kernel functions may be executed.
Definition: context.hpp:39
bool has_property() const noexcept
std::shared_ptr< detail::image_impl > impl
Definition: image.hpp:162
An event object can be used to synchronize memory transfers, enqueues of kernels and signaling barrie...
Definition: event.hpp:38
Command group handler class.
Definition: handler.hpp:310
Defines a shared image data.
Definition: image.hpp:181
void set_final_data_internal(std::weak_ptr< WeakT > FinalData)
Definition: image.hpp:428
image(const image &rhs)=default
image(void *HostPointer, image_channel_order Order, image_channel_type Type, const range< Dimensions > &Range, const property_list &PropList={})
Definition: image.hpp:225
image(std::shared_ptr< void > &HostPointer, image_channel_order Order, image_channel_type Type, const range< Dimensions > &Range, const property_list &PropList={})
Definition: image.hpp:286
~image()=default
image(image_channel_order Order, image_channel_type Type, const range< Dimensions > &Range, AllocatorT Allocator, const property_list &PropList={})
Definition: image.hpp:191
accessor< detail::EnableIfImgAccDataT< DataT >, Dimensions, AccessMode, access::target::image, access::placeholder::false_t, ext::oneapi::accessor_property_list<> > get_access(handler &commandGroupHandler)
Definition: image.hpp:393
image(std::shared_ptr< void > &HostPointer, image_channel_order Order, image_channel_type Type, const range< Dimensions > &Range, const typename detail::enable_if_t< B, range< Dimensions - 1 >> &Pitch, const property_list &PropList={})
Definition: image.hpp:306
void set_final_data_internal(std::nullptr_t)
Definition: image.hpp:415
image(std::shared_ptr< void > &HostPointer, image_channel_order Order, image_channel_type Type, const range< Dimensions > &Range, AllocatorT Allocator, const property_list &PropList={})
Definition: image.hpp:295
image(void *HostPointer, image_channel_order Order, image_channel_type Type, const range< Dimensions > &Range, const typename detail::enable_if_t< B, range< Dimensions - 1 >> &Pitch, AllocatorT Allocator, const property_list &PropList={})
Definition: image.hpp:275
void set_write_back(bool flag=true)
Definition: image.hpp:466
image(std::shared_ptr< void > &HostPointer, image_channel_order Order, image_channel_type Type, const range< Dimensions > &Range, const typename detail::enable_if_t< B, range< Dimensions - 1 >> &Pitch, AllocatorT Allocator, const property_list &PropList={})
Definition: image.hpp:319
image(const void *HostPointer, image_channel_order Order, image_channel_type Type, const range< Dimensions > &Range, AllocatorT Allocator, const property_list &PropList={})
Definition: image.hpp:251
bool operator!=(const image &rhs) const
Definition: image.hpp:353
range< Dimensions > get_range() const
Definition: image.hpp:364
image(image &&rhs)=default
detail::enable_if_t< std::is_convertible< WeakPtrT< WeakT >, std::weak_ptr< WeakT > >::value > set_final_data_internal(WeakPtrT< WeakT > FinalData)
Definition: image.hpp:422
size_t size() const noexcept
Definition: image.hpp:381
AllocatorT get_allocator() const
Definition: image.hpp:384
image(void *HostPointer, image_channel_order Order, image_channel_type Type, const range< Dimensions > &Range, AllocatorT Allocator, const property_list &PropList={})
Definition: image.hpp:233
image(const void *HostPointer, image_channel_order Order, image_channel_type Type, const range< Dimensions > &Range, const property_list &PropList={})
Definition: image.hpp:242
accessor< detail::EnableIfImgAccDataT< DataT >, Dimensions, AccessMode, access::target::host_image, access::placeholder::false_t, ext::oneapi::accessor_property_list<> > get_access()
Definition: image.hpp:404
detail::EnableIfOutputPointerT< Destination > set_final_data_internal(Destination FinalData)
Definition: image.hpp:438
image(void *HostPointer, image_channel_order Order, image_channel_type Type, const range< Dimensions > &Range, const typename detail::enable_if_t< B, range< Dimensions - 1 >> &Pitch, const property_list &PropList={})
Definition: image.hpp:262
__SYCL2020_DEPRECATED("get_count() is deprecated, please use size() instead") size_t get_count() const
Definition: image.hpp:379
detail::enable_if_t< B, range< Dimensions - 1 > > get_pitch() const
Definition: image.hpp:370
image & operator=(image &&rhs)=default
bool has_property() const noexcept
Definition: image.hpp:356
bool operator==(const image &rhs) const
Definition: image.hpp:351
image & operator=(const image &rhs)=default
detail::EnableIfOutputIteratorT< Destination > set_final_data_internal(Destination FinalData)
Definition: image.hpp:450
void set_final_data(Destination finalData=nullptr)
Definition: image.hpp:411
propertyT get_property() const
Definition: image.hpp:360
image(image_channel_order Order, image_channel_type Type, const range< Dimensions > &Range, const typename detail::enable_if_t< B, range< Dimensions - 1 >> &Pitch, const property_list &PropList={})
Definition: image.hpp:202
image(image_channel_order Order, image_channel_type Type, const range< Dimensions > &Range, const property_list &PropList={})
Definition: image.hpp:184
size_t get_size() const
Definition: image.hpp:376
image(image_channel_order Order, image_channel_type Type, const range< Dimensions > &Range, const typename detail::enable_if_t< B, range< Dimensions - 1 >> &Pitch, AllocatorT Allocator, const property_list &PropList={})
Definition: image.hpp:214
Objects of the property_list class are containers for the SYCL properties.
#define __SYCL_INLINE_VER_NAMESPACE(X)
static T< NewDim > convertToArrayOfN(T< OldDim > OldObj)
Definition: common.hpp:399
detail::enable_if_t< std::is_pointer< DataT >::value > EnableIfOutputPointerT
Definition: common.hpp:34
typename detail::enable_if_t< is_validImageDataT< DataT >::value, DataT > EnableIfImgAccDataT
Definition: image.hpp:78
typename std::iterator_traits< T >::value_type iterator_value_type_t
detail::enable_if_t< !std::is_pointer< DataT >::value > EnableIfOutputIteratorT
Definition: common.hpp:38
decltype(Obj::impl) getSyclObjImpl(const Obj &SyclObject)
Definition: common.hpp:240
typename std::enable_if< B, T >::type enable_if_t
typename detail::is_contained< T, type_list< cl_int4, cl_uint4, cl_float4, cl_half4 > >::type is_validImageDataT
Definition: image.hpp:74
static constexpr std::enable_if_t< HasProperty, typename FindCompileTimePropertyValueType< CTPropertyT, PropertiesT >::type > get_property()
Definition: properties.hpp:65
class __SYCL_SPECIAL_CLASS __SYCL_TYPE(local_accessor) local_accessor class __SYCL_SPECIAL_CLASS IsPlaceholder
Definition: accessor.hpp:2749
std::unique_ptr< T > make_unique_ptr(ArgsT &&...Args)
Definition: stl.hpp:52
class __SYCL_SPECIAL_CLASS __SYCL_TYPE(local_accessor) local_accessor class __SYCL_SPECIAL_CLASS Dimensions
Definition: accessor.hpp:2747
image_channel_order
Definition: image.hpp:27
image_channel_type
Definition: image.hpp:45
class __SYCL_SPECIAL_CLASS __SYCL_TYPE(local_accessor) local_accessor class __SYCL_SPECIAL_CLASS AccessMode
Definition: accessor.hpp:2747
---— Error handling, matching OpenCL plugin semantics.
Definition: access.hpp:14
size_t operator()(const sycl::image< Dimensions, AllocatorT > &I) const
Definition: image.hpp:505