1 #ifndef ANDROID_DVR_PRODUCER_BUFFER_H_ 2 #define ANDROID_DVR_PRODUCER_BUFFER_H_ 3 4 #include <private/dvr/buffer_hub_base.h> 5 6 namespace android { 7 namespace dvr { 8 9 // This represents a writable buffer. Calling Post notifies all clients and 10 // makes the buffer read-only. Call Gain to acquire write access. A buffer 11 // may have many consumers. 12 // 13 // The user of ProducerBuffer is responsible with making sure that the Post() is 14 // done with the correct metadata type and size. The user is also responsible 15 // for making sure that remote ends (ConsumerBuffers) are also using the correct 16 // metadata when acquiring the buffer. The API guarantees that a Post() with a 17 // metadata of wrong size will fail. However, it currently does not do any 18 // type checking. 19 // The API also assumes that metadata is a serializable type (plain old data). 20 class ProducerBuffer : public pdx::ClientBase<ProducerBuffer, BufferHubBase> { 21 public: 22 // Imports a bufferhub producer channel, assuming ownership of its handle. 23 static std::unique_ptr<ProducerBuffer> Import(LocalChannelHandle channel); 24 static std::unique_ptr<ProducerBuffer> Import( 25 Status<LocalChannelHandle> status); 26 27 // Asynchronously posts a buffer. The fence and metadata are passed to 28 // consumer via shared fd and shared memory. 29 int PostAsync(const DvrNativeBufferMetadata* meta, 30 const LocalHandle& ready_fence); 31 32 // Post this buffer, passing |ready_fence| to the consumers. The bytes in 33 // |meta| are passed unaltered to the consumers. The producer must not modify 34 // the buffer until it is re-gained. 35 // This returns zero or a negative unix error code. 36 int Post(const LocalHandle& ready_fence, const void* meta, 37 size_t user_metadata_size); 38 39 int Post(const LocalHandle& ready_fence) { 40 return Post(ready_fence, nullptr, 0); 41 } 42 43 // Attempt to re-gain the buffer for writing. If |release_fence| is valid, it 44 // must be waited on before using the buffer. If it is not valid then the 45 // buffer is free for immediate use. This call will succeed if the buffer 46 // is in the released state, or in posted state and gain_posted_buffer is 47 // true. 48 // 49 // @param release_fence output fence. 50 // @param gain_posted_buffer whether to gain posted buffer or not. 51 // @return This returns zero or a negative unix error code. 52 int Gain(LocalHandle* release_fence, bool gain_posted_buffer = false); 53 54 // Asynchronously marks a released buffer as gained. This method is similar to 55 // the synchronous version above, except that it does not wait for BufferHub 56 // to acknowledge success or failure. Because of the asynchronous nature of 57 // the underlying message, no error is returned if this method is called when 58 // the buffer is in an incorrect state. Returns zero if sending the message 59 // succeeded, or a negative errno code if local error check fails. 60 // TODO(b/112007999): gain_posted_buffer true is only used to prevent 61 // libdvrtracking from starving when there are non-responding clients. This 62 // gain_posted_buffer param can be removed once libdvrtracking start to use 63 // the new AHardwareBuffer API. 64 int GainAsync(DvrNativeBufferMetadata* out_meta, LocalHandle* out_fence, 65 bool gain_posted_buffer = false); 66 int GainAsync(); 67 68 // Detaches a ProducerBuffer from an existing producer/consumer set. Can only 69 // be called when a producer buffer has exclusive access to the buffer (i.e. 70 // in the gain'ed state). On the successful return of the IPC call, a new 71 // LocalChannelHandle representing a detached buffer will be returned and all 72 // existing producer and consumer channels will be closed. Further IPCs 73 // towards those channels will return error. 74 Status<LocalChannelHandle> Detach(); 75 76 private: 77 friend BASE; 78 79 // Constructors are automatically exposed through ProducerBuffer::Create(...) 80 // static template methods inherited from ClientBase, which take the same 81 // arguments as the constructors. 82 83 // Constructs a buffer with the given geometry and parameters. 84 ProducerBuffer(uint32_t width, uint32_t height, uint32_t format, 85 uint64_t usage, size_t metadata_size = 0); 86 87 // Constructs a blob (flat) buffer with the given usage flags. 88 ProducerBuffer(uint64_t usage, size_t size); 89 90 // Imports the given file handle to a producer channel, taking ownership. 91 explicit ProducerBuffer(LocalChannelHandle channel); 92 93 // Local state transition helpers. 94 int LocalGain(DvrNativeBufferMetadata* out_meta, LocalHandle* out_fence, 95 bool gain_posted_buffer = false); 96 int LocalPost(const DvrNativeBufferMetadata* meta, 97 const LocalHandle& ready_fence); 98 }; 99 100 } // namespace dvr 101 } // namespace android 102 103 #endif // ANDROID_DVR_PRODUCER_BUFFER_H_ 104
