1 // Copyright 2018 The Chromium Authors 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 BASE_ANDROID_SCOPED_HARDWARE_BUFFER_HANDLE_H_ 6 #define BASE_ANDROID_SCOPED_HARDWARE_BUFFER_HANDLE_H_ 7 8 #include "base/base_export.h" 9 #include "base/files/scoped_file.h" 10 #include "base/memory/raw_ptr.h" 11 12 extern "C" typedef struct AHardwareBuffer AHardwareBuffer; 13 14 namespace base { 15 namespace android { 16 17 // Owns a single reference to an AHardwareBuffer object. 18 class BASE_EXPORT ScopedHardwareBufferHandle { 19 public: 20 ScopedHardwareBufferHandle(); 21 22 // Takes ownership of |other|'s buffer reference. Does NOT acquire a new one. 23 ScopedHardwareBufferHandle(ScopedHardwareBufferHandle&& other); 24 25 ScopedHardwareBufferHandle(const ScopedHardwareBufferHandle&) = delete; 26 ScopedHardwareBufferHandle& operator=(const ScopedHardwareBufferHandle&) = 27 delete; 28 29 // Releases this handle's reference to the underlying buffer object if still 30 // valid. 31 ~ScopedHardwareBufferHandle(); 32 33 // Assumes ownership of an existing reference to |buffer|. This does NOT 34 // acquire a new reference. 35 static ScopedHardwareBufferHandle Adopt(AHardwareBuffer* buffer); 36 37 // Adds a reference to |buffer| managed by this handle. 38 static ScopedHardwareBufferHandle Create(AHardwareBuffer* buffer); 39 40 // Takes ownership of |other|'s buffer reference. Does NOT acquire a new one. 41 ScopedHardwareBufferHandle& operator=(ScopedHardwareBufferHandle&& other); 42 43 bool is_valid() const; 44 45 AHardwareBuffer* get() const; 46 47 // Releases this handle's reference to the underlying buffer object if still 48 // valid. Invalidates this handle. 49 void reset(); 50 51 // Passes implicit ownership of this handle's reference over to the caller, 52 // invalidating |this|. Returns the raw buffer handle. 53 // 54 // The caller is responsible for eventually releasing this reference to the 55 // buffer object. 56 [[nodiscard]] AHardwareBuffer* Take(); 57 58 // Creates a new handle with its own newly acquired reference to the 59 // underlying buffer object. |this| must be a valid handle. 60 ScopedHardwareBufferHandle Clone() const; 61 62 // Consumes a handle and returns a file descriptor which can be used to 63 // transmit the handle over IPC. A subsequent receiver may use 64 // |DeserializeFromFileDescriptor()| to recover the buffer handle. 65 // 66 // NOTE: The returned file descriptor DOES NOT own a reference to the 67 // underlying AHardwareBuffer. When using this for IPC, the caller is 68 // responsible for retaining at least one reference to the buffer object to 69 // keep it alive while the descriptor is in transit. 70 ScopedFD SerializeAsFileDescriptor() const; 71 72 // Consumes the supplied single-use file descriptor (which must have been 73 // returned by a previous call to |SerializeAsFileDescriptor()|, perhaps in 74 // a different process), and recovers an AHardwareBuffer object from it. 75 // 76 // This acquires a new reference to the AHardwareBuffer, with ownership passed 77 // to the caller via the returned ScopedHardwareBufferHandle. 78 [[nodiscard]] static ScopedHardwareBufferHandle DeserializeFromFileDescriptor( 79 ScopedFD fd); 80 81 private: 82 // Assumes ownership of an existing reference to |buffer|. This does NOT 83 // acquire a new reference. 84 explicit ScopedHardwareBufferHandle(AHardwareBuffer* buffer); 85 86 raw_ptr<AHardwareBuffer> buffer_ = nullptr; 87 }; 88 89 } // namespace android 90 } // namespace base 91 92 #endif // BASE_ANDROID_SCOPED_HARDWARE_BUFFER_HANDLE_H_ 93