Flutter Impeller
hardware_buffer.h
Go to the documentation of this file.
1 // Copyright 2013 The Flutter Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef FLUTTER_IMPELLER_TOOLKIT_ANDROID_HARDWARE_BUFFER_H_
6 #define FLUTTER_IMPELLER_TOOLKIT_ANDROID_HARDWARE_BUFFER_H_
7 
8 #include <optional>
9 
10 #include "flutter/fml/unique_object.h"
11 #include "impeller/geometry/size.h"
13 
14 namespace impeller::android {
15 
17  //----------------------------------------------------------------------------
18  /// This format is guaranteed to be supported on all versions of Android. This
19  /// format can also be converted to an Impeller and Vulkan format.
20  ///
21  /// @see Vulkan Format: VK_FORMAT_R8G8B8A8_UNORM
22  /// @see OpenGL ES Format: GL_RGBA8
23  ///
24  /// Why have many format when one format do trick?
25  ///
27 };
28 
29 using HardwareBufferUsage = uint8_t;
30 
32  kFrameBufferAttachment = 1u << 0u,
33  kCompositorOverlay = 1u << 1u,
34  kSampledImage = 1u << 2u,
35 };
36 
37 //------------------------------------------------------------------------------
38 /// @brief A descriptor use to specify hardware buffer allocations.
39 ///
44 
45  //----------------------------------------------------------------------------
46  /// @brief Create a descriptor of the given size that is suitable for use
47  /// as a swapchain image.
48  ///
49  /// @warning Descriptors of zero size are not allocatable. The next best
50  /// valid size is picked. So make sure to check the actual size of
51  /// the descriptor after this call is made to determine the size
52  /// of the allocated hardware buffer.
53  ///
54  /// @param[in] size The size. See the restrictions about valid sizes above.
55  ///
56  /// @return The hardware buffer descriptor.
57  ///
59 
60  //----------------------------------------------------------------------------
61  /// @brief If hardware buffers can be created using this descriptor.
62  /// Allocatable descriptors may still cause failing allocations in
63  /// case of resource exhaustion.
64  ///
65  /// @return `true` if allocatable (unless resource exhaustion).
66  ///
67  bool IsAllocatable() const;
68 
69  constexpr bool operator==(const HardwareBufferDescriptor& o) const {
70  return format == o.format && size == o.size && usage == o.usage;
71  }
72 
73  constexpr bool operator!=(const HardwareBufferDescriptor& o) const {
74  return !(*this == o);
75  }
76 };
77 
78 //------------------------------------------------------------------------------
79 /// @brief A wrapper for AHardwareBuffer
80 /// https://developer.android.com/ndk/reference/group/a-hardware-buffer
81 ///
82 /// This wrapper creates and owns a handle to a managed hardware
83 /// buffer. That is, there is no ability to take a reference to an
84 /// externally created hardware buffer.
85 ///
86 /// This wrapper is only available on Android API 29 and above.
87 ///
89  public:
90  static bool IsAvailableOnPlatform();
91 
92  explicit HardwareBuffer(HardwareBufferDescriptor descriptor);
93 
95 
96  HardwareBuffer(const HardwareBuffer&) = delete;
97 
98  HardwareBuffer& operator=(const HardwareBuffer&) = delete;
99 
100  bool IsValid() const;
101 
102  AHardwareBuffer* GetHandle() const;
103 
105 
106  const AHardwareBuffer_Desc& GetAndroidDescriptor() const;
107 
108  static std::optional<AHardwareBuffer_Desc> Describe(AHardwareBuffer* buffer);
109 
110  //----------------------------------------------------------------------------
111  /// @brief Get the system wide unique ID of the hardware buffer if
112  /// possible. This is only available on Android API 31 and above.
113  /// Within the process, the handle are unique.
114  ///
115  /// @return The system unique id if one can be obtained.
116  ///
117  std::optional<uint64_t> GetSystemUniqueID() const;
118 
119  //----------------------------------------------------------------------------
120  /// @brief Get the system wide unique ID of the hardware buffer if
121  /// possible. This is only available on Android API 31 and above.
122  /// Within the process, the handle are unique.
123  ///
124  /// @return The system unique id if one can be obtained.
125  ///
126  static std::optional<uint64_t> GetSystemUniqueID(AHardwareBuffer* buffer);
127 
128  private:
129  struct UniqueAHardwareBufferTraits {
130  static AHardwareBuffer* InvalidValue() { return nullptr; }
131 
132  static bool IsValid(AHardwareBuffer* value) {
133  return value != InvalidValue();
134  }
135 
136  static void Free(AHardwareBuffer* value) {
137  GetProcTable().AHardwareBuffer_release(value);
138  }
139  };
140 
141  const HardwareBufferDescriptor descriptor_;
142  const AHardwareBuffer_Desc android_descriptor_;
143  fml::UniqueObject<AHardwareBuffer*, UniqueAHardwareBufferTraits> buffer_;
144  bool is_valid_ = false;
145 };
146 
147 } // namespace impeller::android
148 
149 #endif // FLUTTER_IMPELLER_TOOLKIT_ANDROID_HARDWARE_BUFFER_H_
impeller::android::HardwareBuffer::IsAvailableOnPlatform
static bool IsAvailableOnPlatform()
Definition: hardware_buffer.cc:100
impeller::android::HardwareBufferUsage
uint8_t HardwareBufferUsage
Definition: hardware_buffer.h:29
impeller::android::HardwareBufferUsageFlags::kCompositorOverlay
@ kCompositorOverlay
impeller::android::HardwareBuffer::GetSystemUniqueID
std::optional< uint64_t > GetSystemUniqueID() const
Get the system wide unique ID of the hardware buffer if possible. This is only available on Android A...
Definition: hardware_buffer.cc:104
impeller::android::HardwareBuffer::GetDescriptor
const HardwareBufferDescriptor & GetDescriptor() const
Definition: hardware_buffer.cc:92
impeller::android::HardwareBuffer::operator=
HardwareBuffer & operator=(const HardwareBuffer &)=delete
impeller::android::HardwareBufferUsageFlags::kSampledImage
@ kSampledImage
impeller::android::HardwareBufferDescriptor::MakeForSwapchainImage
static HardwareBufferDescriptor MakeForSwapchainImage(const ISize &size)
Create a descriptor of the given size that is suitable for use as a swapchain image.
Definition: hardware_buffer.cc:77
impeller::android
Definition: choreographer.cc:9
impeller::TSize< int64_t >
impeller::android::HardwareBuffer
A wrapper for AHardwareBuffer https://developer.android.com/ndk/reference/group/a-hardware-buffer.
Definition: hardware_buffer.h:88
impeller::android::HardwareBufferFormat
HardwareBufferFormat
Definition: hardware_buffer.h:16
impeller::android::HardwareBufferUsageFlags
HardwareBufferUsageFlags
Definition: hardware_buffer.h:31
impeller::android::HardwareBufferDescriptor::operator!=
constexpr bool operator!=(const HardwareBufferDescriptor &o) const
Definition: hardware_buffer.h:73
proc_table.h
impeller::android::HardwareBufferDescriptor::operator==
constexpr bool operator==(const HardwareBufferDescriptor &o) const
Definition: hardware_buffer.h:69
impeller::android::HardwareBuffer::~HardwareBuffer
~HardwareBuffer()
impeller::android::HardwareBufferFormat::kR8G8B8A8UNormInt
@ kR8G8B8A8UNormInt
impeller::android::HardwareBufferDescriptor
A descriptor use to specify hardware buffer allocations.
Definition: hardware_buffer.h:40
impeller::android::HardwareBuffer::GetHandle
AHardwareBuffer * GetHandle() const
Definition: hardware_buffer.cc:73
impeller::android::HardwareBufferDescriptor::size
ISize size
Definition: hardware_buffer.h:42
impeller::android::HardwareBuffer::Describe
static std::optional< AHardwareBuffer_Desc > Describe(AHardwareBuffer *buffer)
Definition: hardware_buffer.cc:120
impeller::android::HardwareBufferDescriptor::usage
HardwareBufferUsage usage
Definition: hardware_buffer.h:43
impeller::android::HardwareBuffer::HardwareBuffer
HardwareBuffer(HardwareBufferDescriptor descriptor)
Definition: hardware_buffer.cc:47
impeller::android::GetProcTable
const ProcTable & GetProcTable()
Definition: proc_table.cc:12
impeller::android::HardwareBuffer::IsValid
bool IsValid() const
Definition: hardware_buffer.cc:69
impeller::android::HardwareBufferUsageFlags::kFrameBufferAttachment
@ kFrameBufferAttachment
impeller::android::HardwareBufferDescriptor::format
HardwareBufferFormat format
Definition: hardware_buffer.h:41
impeller::android::HardwareBufferDescriptor::IsAllocatable
bool IsAllocatable() const
If hardware buffers can be created using this descriptor. Allocatable descriptors may still cause fai...
Definition: hardware_buffer.cc:42
impeller::android::HardwareBuffer::GetAndroidDescriptor
const AHardwareBuffer_Desc & GetAndroidDescriptor() const
Definition: hardware_buffer.cc:96
size.h