| 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"
12 #include "impeller/toolkit/android/proc_table.h"
13
14 namespace impeller::android {
15
16 enum class HardwareBufferFormat {
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 ///
26 kR8G8B8A8UNormInt,
27 };
28
29 using HardwareBufferUsage = uint8_t;
30
31 enum class HardwareBufferUsageFlags : HardwareBufferUsage {
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 ///
40 struct HardwareBufferDescriptor {
41 HardwareBufferFormat format = HardwareBufferFormat::kR8G8B8A8UNormInt;
42 ISize size;
43 HardwareBufferUsage usage = 0u;
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 ///
58 static HardwareBufferDescriptor MakeForSwapchainImage(const ISize& size);
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 ///
88 class HardwareBuffer {
89 public:
90 static bool IsAvailableOnPlatform();
91
92 explicit HardwareBuffer(HardwareBufferDescriptor descriptor);
93
94 ~HardwareBuffer();
95
96 HardwareBuffer(const HardwareBuffer&) = delete;
97
98 HardwareBuffer& operator=(const HardwareBuffer&) = delete;
99
100 bool IsValid() const;
101
102 AHardwareBuffer* GetHandle() const;
103
104 const HardwareBufferDescriptor& GetDescriptor() const;
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