dvr_buffer_queue.h revision 97274870fc8229b507fc71566c0502eb322655cf
1#ifndef ANDROID_DVR_BUFFER_QUEUE_H_ 2#define ANDROID_DVR_BUFFER_QUEUE_H_ 3 4#include <sys/cdefs.h> 5 6#include <dvr/dvr_buffer.h> 7 8__BEGIN_DECLS 9 10typedef struct ANativeWindow ANativeWindow; 11 12typedef struct DvrWriteBufferQueue DvrWriteBufferQueue; 13typedef struct DvrReadBufferQueue DvrReadBufferQueue; 14 15// Destroy a write buffer queue. 16// 17// @param write_queue The DvrWriteBufferQueue of interest. 18void dvrWriteBufferQueueDestroy(DvrWriteBufferQueue* write_queue); 19 20// Get the total number of buffers in a write buffer queue. 21// 22// @param write_queue The DvrWriteBufferQueue of interest. 23// @return The capacity on success; or negative error code. 24ssize_t dvrWriteBufferQueueGetCapacity(DvrWriteBufferQueue* write_queue); 25 26// Get the system unique queue id of a write buffer queue. 27// 28// @param write_queue The DvrWriteBufferQueue of interest. 29// @return Queue id on success; or negative error code. 30int dvrWriteBufferQueueGetId(DvrWriteBufferQueue* write_queue); 31 32// Gets an ANativeWindow backed by the DvrWriteBufferQueue 33// 34// Can be casted to a Java Surface using ANativeWindow_toSurface NDK API. Note 35// that the native window is lazily created at the first time |GetNativeWindow| 36// is called, and the created ANativeWindow will be cached so that multiple 37// calls to this method will return the same object. Also note that this method 38// does not acquire an additional reference to the ANativeWindow returned, don't 39// call ANativeWindow_release on it. 40// 41// @param write_queue The DvrWriteBufferQueue of interest. 42// @param out_window The pointer of an ANativeWindow will be filled here if 43// the method call succeeds. 44// @return Zero on success; or -EINVAL if this DvrWriteBufferQueue does not 45// support being used as an android Surface. 46int dvrWriteBufferQueueGetExternalSurface(DvrWriteBufferQueue* write_queue, 47 ANativeWindow** out_window); 48 49// Create a read buffer queue from an existing write buffer queue. 50// 51// @param write_queue The DvrWriteBufferQueue of interest. 52// @param out_read_queue The pointer of a DvrReadBufferQueue will be filled here 53// if the method call succeeds. 54// @return Zero on success, or negative error code. 55int dvrWriteBufferQueueCreateReadQueue(DvrWriteBufferQueue* write_queue, 56 DvrReadBufferQueue** out_read_queue); 57 58// Dequeue a buffer to write into. 59// 60// @param write_queue The DvrWriteBufferQueue of interest. 61// @param timeout Specifies the number of milliseconds that the method will 62// block. Specifying a timeout of -1 causes it to block indefinitely, 63// while specifying a timeout equal to zero cause it to return immediately, 64// even if no buffers are available. 65// @param out_buffer A targeting DvrWriteBuffer object to hold the output of the 66// dequeue operation. Must be created by |dvrWriteBufferCreateEmpty|. 67// @param out_fence_fd A sync fence fd defined in NDK's sync.h API, which 68// signals the release of underlying buffer. The producer should wait until 69// this fence clears before writing data into it. 70// @return Zero on success, or negative error code. 71int dvrWriteBufferQueueDequeue(DvrWriteBufferQueue* write_queue, int timeout, 72 DvrWriteBuffer* out_buffer, int* out_fence_fd); 73 74// Overrides buffer dimension with new width and height. 75// 76// After the call successfully returns, each |dvrWriteBufferQueueDequeue| call 77// will return buffer with newly assigned |width| and |height|. When necessary, 78// old buffer will be removed from the buffer queue and replaced with new buffer 79// matching the new buffer size. 80// 81// @param write_queue The DvrWriteBufferQueue of interest. 82// @param width Desired width, cannot be Zero. 83// @param height Desired height, cannot be Zero. 84// @return Zero on success, or negative error code. 85int dvrWriteBufferQueueResizeBuffer(DvrWriteBufferQueue* write_queue, 86 uint32_t width, uint32_t height); 87 88// Destroy a read buffer queue. 89// 90// @param read_queue The DvrReadBufferQueue of interest. 91void dvrReadBufferQueueDestroy(DvrReadBufferQueue* read_queue); 92 93// Get the total number of buffers in a read buffer queue. 94// 95// @param read_queue The DvrReadBufferQueue of interest. 96// @return The capacity on success; or negative error code. 97ssize_t dvrReadBufferQueueGetCapacity(DvrReadBufferQueue* read_queue); 98 99// Get the system unique queue id of a read buffer queue. 100// 101// @param read_queue The DvrReadBufferQueue of interest. 102// @return Queue id on success; or negative error code. 103int dvrReadBufferQueueGetId(DvrReadBufferQueue* read_queue); 104 105// Get the event fd that signals when queue updates occur. 106// 107// Use ReadBufferQueueHandleEvents to trigger registered event callbacks. 108// 109// @param read_queue The DvrReadBufferQueue of interest. 110// @return Fd on success; or negative error code. 111int dvrReadBufferQueueGetEventFd(DvrReadBufferQueue* read_queue); 112 113// Create a read buffer queue from an existing read buffer queue. 114// 115// @param read_queue The DvrReadBufferQueue of interest. 116// @param out_read_queue The pointer of a DvrReadBufferQueue will be filled here 117// if the method call succeeds. 118// @return Zero on success, or negative error code. 119int dvrReadBufferQueueCreateReadQueue(DvrReadBufferQueue* read_queue, 120 DvrReadBufferQueue** out_read_queue); 121 122// Dequeue a buffer to read from. 123// 124// @param read_queue The DvrReadBufferQueue of interest. 125// @param timeout Specifies the number of milliseconds that the method will 126// block. Specifying a timeout of -1 causes it to block indefinitely, 127// while specifying a timeout equal to zero cause it to return immediately, 128// even if no buffers are available. 129// @param out_buffer A targeting DvrReadBuffer object to hold the output of the 130// dequeue operation. Must be created by |dvrReadBufferCreateEmpty|. 131// @param out_fence_fd A sync fence fd defined in NDK's sync.h API, which 132// signals the release of underlying buffer. The consumer should wait until 133// this fence clears before reading data from it. 134// @param out_meta The memory area where a metadata object will be filled. 135// Can be nullptr iff |meta_size_bytes| is zero (i.e., there is no 136// metadata). 137// @param meta_size_bytes Size of the metadata object caller expects. If it 138// doesn't match the size of actually metadata transported by the buffer 139// queue, the method returns -EINVAL. 140// @return Zero on success, or negative error code. 141int dvrReadBufferQueueDequeue(DvrReadBufferQueue* read_queue, int timeout, 142 DvrReadBuffer* out_buffer, int* out_fence_fd, 143 void* out_meta, size_t meta_size_bytes); 144 145// Callback function which will be called when a buffer is avaiable. 146// 147// Note that there is no guarantee of thread safety and on which thread the 148// callback will be fired. 149// 150// @param context User provided opaque pointer. 151typedef void (*DvrReadBufferQueueBufferAvailableCallback)(void* context); 152 153// Set buffer avaiable callback. 154// 155// @param read_queue The DvrReadBufferQueue of interest. 156// @param callback The callback function. Set this to NULL if caller no longer 157// needs to listen to new buffer available events. 158// @param context User provided opaque pointer, will be passed back during 159// callback. The caller is responsible for ensuring the validity of the 160// context through the life cycle of the DvrReadBufferQueue. 161// @return Zero on success, or negative error code. 162int dvrReadBufferQueueSetBufferAvailableCallback( 163 DvrReadBufferQueue* read_queue, 164 DvrReadBufferQueueBufferAvailableCallback callback, void* context); 165 166// Callback function which will be called when a buffer is about to be removed. 167// 168// Note that there is no guarantee of thread safety and on which thread the 169// callback will be fired. 170// 171// @param buffer The buffer being removed. Once the callbacks returns, this 172// buffer will be dereferenced from the buffer queue. If user has ever 173// cached other DvrReadBuffer/AHardwareBuffer/EglImageKHR objects derived 174// from this buffer, it's the user's responsibility to clean them up. 175// Note that the ownership of the read buffer is not passed to this 176// callback, so it should call dvrReadBufferDestroy on the buffer. 177// @param context User provided opaque pointer. 178typedef void (*DvrReadBufferQueueBufferRemovedCallback)(DvrReadBuffer* buffer, 179 void* context); 180 181// Set buffer removed callback. 182// 183// @param read_queue The DvrReadBufferQueue of interest. 184// @param callback The callback function. Set this to NULL if caller no longer 185// needs to listen to buffer removed events. 186// @param context User provided opaque pointer, will be passed back during 187// callback. The caller is responsible for ensuring the validity of the 188// context through the life cycle of the DvrReadBufferQueue. 189// @return Zero on success, or negative error code. 190int dvrReadBufferQueueSetBufferRemovedCallback( 191 DvrReadBufferQueue* read_queue, 192 DvrReadBufferQueueBufferRemovedCallback callback, void* context); 193 194// Handle all pending events on the read queue. 195// 196// @param read_queue The DvrReadBufferQueue of interest. 197// @return Zero on success, or negative error code. 198int dvrReadBufferQueueHandleEvents(DvrReadBufferQueue* read_queue); 199 200__END_DECLS 201 202#endif // ANDROID_DVR_BUFFER_QUEUE_H_ 203