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 10 typedef struct ANativeWindow ANativeWindow; 11 12 typedef struct DvrWriteBufferQueue DvrWriteBufferQueue; 13 typedef struct DvrReadBufferQueue DvrReadBufferQueue; 14 15 // Creates a write buffer queue to be used locally. 16 // 17 // Note that this API is mostly for testing purpose. For now there is no 18 // mechanism to send a DvrWriteBufferQueue cross process. Use 19 // dvrSurfaceCreateWriteBufferQueue if cross-process buffer transport is 20 // intended. 21 // 22 // @param width The width of the buffers that this queue will produce. 23 // @param height The height of buffers that this queue will produce. 24 // @param format The format of the buffers that this queue will produce. This 25 // must be one of the AHARDWAREBUFFER_FORMAT_XXX enums. 26 // @param layer_count The number of layers of the buffers that this queue will 27 // produce. 28 // @param usage The usage of the buffers that this queue will produce. This 29 // must a combination of the AHARDWAREBUFFER_USAGE_XXX flags. 30 // @param capacity The number of buffer that this queue will allocate. Note that 31 // all buffers will be allocated on create. Currently, the number of buffers 32 // is the queue cannot be changed after creation though DVR API. However, 33 // ANativeWindow can choose to reallocate, attach, or detach buffers from 34 // a DvrWriteBufferQueue through Android platform logic. 35 // @param metadata_size The size of metadata in bytes. 36 // @param out_write_queue The pointer of a DvrWriteBufferQueue will be filled 37 // here if the method call succeeds. The metadata size must match 38 // the metadata size in dvrWriteBufferPost/dvrReadBufferAcquire. 39 // @return Zero on success, or negative error code. 40 int dvrWriteBufferQueueCreate(uint32_t width, uint32_t height, uint32_t format, 41 uint32_t layer_count, uint64_t usage, 42 size_t capacity, size_t metadata_size, 43 DvrWriteBufferQueue** out_write_queue); 44 45 // Destroy a write buffer queue. 46 // 47 // @param write_queue The DvrWriteBufferQueue of interest. 48 void dvrWriteBufferQueueDestroy(DvrWriteBufferQueue* write_queue); 49 50 // Get the total number of buffers in a write buffer queue. 51 // 52 // @param write_queue The DvrWriteBufferQueue of interest. 53 // @return The capacity on success; or negative error code. 54 ssize_t dvrWriteBufferQueueGetCapacity(DvrWriteBufferQueue* write_queue); 55 56 // Get the system unique queue id of a write buffer queue. 57 // 58 // @param write_queue The DvrWriteBufferQueue of interest. 59 // @return Queue id on success; or negative error code. 60 int dvrWriteBufferQueueGetId(DvrWriteBufferQueue* write_queue); 61 62 // Gets an ANativeWindow backed by the DvrWriteBufferQueue 63 // 64 // Can be casted to a Java Surface using ANativeWindow_toSurface NDK API. Note 65 // that the native window is lazily created at the first time |GetNativeWindow| 66 // is called, and the created ANativeWindow will be cached so that multiple 67 // calls to this method will return the same object. Also note that this method 68 // does not acquire an additional reference to the ANativeWindow returned, don't 69 // call ANativeWindow_release on it. 70 // 71 // @param write_queue The DvrWriteBufferQueue of interest. 72 // @param out_window The pointer of an ANativeWindow will be filled here if 73 // the method call succeeds. 74 // @return Zero on success; or -EINVAL if this DvrWriteBufferQueue does not 75 // support being used as an android Surface. 76 int dvrWriteBufferQueueGetANativeWindow(DvrWriteBufferQueue* write_queue, 77 ANativeWindow** out_window); 78 79 // Create a read buffer queue from an existing write buffer queue. 80 // 81 // @param write_queue The DvrWriteBufferQueue of interest. 82 // @param out_read_queue The pointer of a DvrReadBufferQueue will be filled here 83 // if the method call succeeds. 84 // @return Zero on success, or negative error code. 85 int dvrWriteBufferQueueCreateReadQueue(DvrWriteBufferQueue* write_queue, 86 DvrReadBufferQueue** out_read_queue); 87 88 // Gains a buffer to write into. 89 // 90 // @param write_queue The DvrWriteBufferQueue to gain buffer from. 91 // @param timeout Specifies the number of milliseconds that the method will 92 // block. Specifying a timeout of -1 causes it to block indefinitely, 93 // while specifying a timeout equal to zero cause it to return immediately, 94 // even if no buffers are available. 95 // @param out_buffer A targeting DvrWriteBuffer object to hold the output of the 96 // dequeue operation. 97 // @param out_meta A DvrNativeBufferMetadata object populated by the 98 // corresponding dvrReadBufferQueueReleaseBuffer API. 99 // @param out_fence_fd A sync fence fd defined in NDK's sync.h API, which 100 // signals the release of underlying buffer. The producer should wait until 101 // this fence clears before writing data into it. 102 // @return Zero on success, or negative error code. 103 int dvrWriteBufferQueueGainBuffer(DvrWriteBufferQueue* write_queue, int timeout, 104 DvrWriteBuffer** out_write_buffer, 105 DvrNativeBufferMetadata* out_meta, 106 int* out_fence_fd); 107 108 // Posts a buffer and signals its readiness to be read from. 109 // 110 // @param write_queue The DvrWriteBufferQueue to post buffer into. 111 // @param write_buffer The buffer to be posted. 112 // @param meta The buffer metadata describing the buffer. 113 // @param ready_fence_fd A sync fence fd defined in NDK's sync.h API, which 114 // signals the readdiness of underlying buffer. When a valid fence gets 115 // passed in, the consumer will wait the fence to be ready before it starts 116 // to ready from the buffer. 117 // @return Zero on success, or negative error code. 118 int dvrWriteBufferQueuePostBuffer(DvrWriteBufferQueue* write_queue, 119 DvrWriteBuffer* write_buffer, 120 const DvrNativeBufferMetadata* meta, 121 int ready_fence_fd); 122 123 // Overrides buffer dimension with new width and height. 124 // 125 // After the call successfully returns, each |dvrWriteBufferQueueDequeue| call 126 // will return buffer with newly assigned |width| and |height|. When necessary, 127 // old buffer will be removed from the buffer queue and replaced with new buffer 128 // matching the new buffer size. 129 // 130 // @param write_queue The DvrWriteBufferQueue of interest. 131 // @param width Desired width, cannot be Zero. 132 // @param height Desired height, cannot be Zero. 133 // @return Zero on success, or negative error code. 134 int dvrWriteBufferQueueResizeBuffer(DvrWriteBufferQueue* write_queue, 135 uint32_t width, uint32_t height); 136 137 // Destroy a read buffer queue. 138 // 139 // @param read_queue The DvrReadBufferQueue of interest. 140 void dvrReadBufferQueueDestroy(DvrReadBufferQueue* read_queue); 141 142 // Get the total number of buffers in a read buffer queue. 143 // 144 // @param read_queue The DvrReadBufferQueue of interest. 145 // @return The capacity on success; or negative error code. 146 ssize_t dvrReadBufferQueueGetCapacity(DvrReadBufferQueue* read_queue); 147 148 // Get the system unique queue id of a read buffer queue. 149 // 150 // @param read_queue The DvrReadBufferQueue of interest. 151 // @return Queue id on success; or negative error code. 152 int dvrReadBufferQueueGetId(DvrReadBufferQueue* read_queue); 153 154 // Get the event fd that signals when queue updates occur. 155 // 156 // Use ReadBufferQueueHandleEvents to trigger registered event callbacks. 157 // 158 // @param read_queue The DvrReadBufferQueue of interest. 159 // @return Fd on success; or negative error code. 160 int dvrReadBufferQueueGetEventFd(DvrReadBufferQueue* read_queue); 161 162 // Create a read buffer queue from an existing read buffer queue. 163 // 164 // @param read_queue The DvrReadBufferQueue of interest. 165 // @param out_read_queue The pointer of a DvrReadBufferQueue will be filled here 166 // if the method call succeeds. 167 // @return Zero on success, or negative error code. 168 int dvrReadBufferQueueCreateReadQueue(DvrReadBufferQueue* read_queue, 169 DvrReadBufferQueue** out_read_queue); 170 171 // Dequeues a buffer to read from. 172 // 173 // @param read_queue The DvrReadBufferQueue to acquire buffer from. 174 // @param timeout Specifies the number of milliseconds that the method will 175 // block. Specifying a timeout of -1 causes it to block indefinitely, 176 // while specifying a timeout equal to zero cause it to return immediately, 177 // even if no buffers are available. 178 // @param out_buffer A targeting DvrReadBuffer object to hold the output of the 179 // dequeue operation. Must be created by |dvrReadBufferCreateEmpty|. 180 // @param out_meta A DvrNativeBufferMetadata object populated by the 181 // corresponding dvrWriteBufferQueuePostBuffer API. 182 // @param out_fence_fd A sync fence fd defined in NDK's sync.h API, which 183 // signals the release of underlying buffer. The consumer should wait until 184 // this fence clears before reading data from it. 185 // @return Zero on success, or negative error code. 186 int dvrReadBufferQueueAcquireBuffer(DvrReadBufferQueue* read_queue, int timeout, 187 DvrReadBuffer** out_read_buffer, 188 DvrNativeBufferMetadata* out_meta, 189 int* out_fence_fd); 190 191 // Releases a buffer and signals its readiness to be written into. 192 // 193 // @param read_queue The DvrReadBufferQueue to release buffer into. 194 // @param read_buffer The buffer to be released. 195 // @param meta The buffer metadata describing the buffer. 196 // @param release_fence_fd A sync fence fd defined in NDK's sync.h API, which 197 // signals the readdiness of underlying buffer. When a valid fence gets 198 // passed in, the producer will wait the fence to be ready before it starts 199 // to write into the buffer again. 200 // @return Zero on success, or negative error code. 201 int dvrReadBufferQueueReleaseBuffer(DvrReadBufferQueue* read_queue, 202 DvrReadBuffer* read_buffer, 203 const DvrNativeBufferMetadata* meta, 204 int release_fence_fd); 205 206 // Callback function which will be called when a buffer is avaiable. 207 // 208 // Note that there is no guarantee of thread safety and on which thread the 209 // callback will be fired. 210 // 211 // @param context User provided opaque pointer. 212 typedef void (*DvrReadBufferQueueBufferAvailableCallback)(void* context); 213 214 // Set buffer avaiable callback. 215 // 216 // @param read_queue The DvrReadBufferQueue of interest. 217 // @param callback The callback function. Set this to NULL if caller no longer 218 // needs to listen to new buffer available events. 219 // @param context User provided opaque pointer, will be passed back during 220 // callback. The caller is responsible for ensuring the validity of the 221 // context through the life cycle of the DvrReadBufferQueue. 222 // @return Zero on success, or negative error code. 223 int dvrReadBufferQueueSetBufferAvailableCallback( 224 DvrReadBufferQueue* read_queue, 225 DvrReadBufferQueueBufferAvailableCallback callback, void* context); 226 227 // Callback function which will be called when a buffer is about to be removed. 228 // 229 // Note that there is no guarantee of thread safety and on which thread the 230 // callback will be fired. 231 // 232 // @param buffer The buffer being removed. Once the callbacks returns, this 233 // buffer will be dereferenced from the buffer queue. If user has ever 234 // cached other DvrReadBuffer/AHardwareBuffer/EglImageKHR objects derived 235 // from this buffer, it's the user's responsibility to clean them up. 236 // Note that the ownership of the read buffer is not passed to this 237 // callback, so it should call dvrReadBufferDestroy on the buffer. 238 // @param context User provided opaque pointer. 239 typedef void (*DvrReadBufferQueueBufferRemovedCallback)(DvrReadBuffer* buffer, 240 void* context); 241 242 // Set buffer removed callback. 243 // 244 // @param read_queue The DvrReadBufferQueue of interest. 245 // @param callback The callback function. Set this to NULL if caller no longer 246 // needs to listen to buffer removed events. 247 // @param context User provided opaque pointer, will be passed back during 248 // callback. The caller is responsible for ensuring the validity of the 249 // context through the life cycle of the DvrReadBufferQueue. 250 // @return Zero on success, or negative error code. 251 int dvrReadBufferQueueSetBufferRemovedCallback( 252 DvrReadBufferQueue* read_queue, 253 DvrReadBufferQueueBufferRemovedCallback callback, void* context); 254 255 // Handle all pending events on the read queue. 256 // 257 // @param read_queue The DvrReadBufferQueue of interest. 258 // @return Zero on success, or negative error code. 259 int dvrReadBufferQueueHandleEvents(DvrReadBufferQueue* read_queue); 260 261 __END_DECLS 262 263 #endif // ANDROID_DVR_BUFFER_QUEUE_H_ 264