1 #ifndef ANDROID_DVR_BUFFER_QUEUE_H_
2 #define ANDROID_DVR_BUFFER_QUEUE_H_
6 #include <dvr/dvr_buffer.h>
10 typedef struct ANativeWindow ANativeWindow;
12 typedef struct DvrWriteBufferQueue DvrWriteBufferQueue;
13 typedef struct DvrReadBufferQueue DvrReadBufferQueue;
15 // Creates a write buffer queue to be used locally.
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
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
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);
45 // Destroy a write buffer queue.
47 // @param write_queue The DvrWriteBufferQueue of interest.
48 void dvrWriteBufferQueueDestroy(DvrWriteBufferQueue* write_queue);
50 // Get the total number of buffers in a write buffer queue.
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);
56 // Get the system unique queue id of a write buffer queue.
58 // @param write_queue The DvrWriteBufferQueue of interest.
59 // @return Queue id on success; or negative error code.
60 int dvrWriteBufferQueueGetId(DvrWriteBufferQueue* write_queue);
62 // Gets an ANativeWindow backed by the DvrWriteBufferQueue
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.
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);
79 // @deprecated Please use dvrWriteBufferQueueGetANativeWindow instead.
80 int dvrWriteBufferQueueGetExternalSurface(DvrWriteBufferQueue* write_queue,
81 ANativeWindow** out_window);
83 // Create a read buffer queue from an existing write buffer queue.
85 // @param write_queue The DvrWriteBufferQueue of interest.
86 // @param out_read_queue The pointer of a DvrReadBufferQueue will be filled here
87 // if the method call succeeds.
88 // @return Zero on success, or negative error code.
89 int dvrWriteBufferQueueCreateReadQueue(DvrWriteBufferQueue* write_queue,
90 DvrReadBufferQueue** out_read_queue);
92 // Dequeue a buffer to write into.
94 // @param write_queue The DvrWriteBufferQueue of interest.
95 // @param timeout Specifies the number of milliseconds that the method will
96 // block. Specifying a timeout of -1 causes it to block indefinitely,
97 // while specifying a timeout equal to zero cause it to return immediately,
98 // even if no buffers are available.
99 // @param out_buffer A targeting DvrWriteBuffer object to hold the output of the
100 // dequeue operation. Must be created by |dvrWriteBufferCreateEmpty|.
101 // @param out_fence_fd A sync fence fd defined in NDK's sync.h API, which
102 // signals the release of underlying buffer. The producer should wait until
103 // this fence clears before writing data into it.
104 // @return Zero on success, or negative error code.
105 int dvrWriteBufferQueueDequeue(DvrWriteBufferQueue* write_queue, int timeout,
106 DvrWriteBuffer* out_buffer, int* out_fence_fd);
108 // Overrides buffer dimension with new width and height.
110 // After the call successfully returns, each |dvrWriteBufferQueueDequeue| call
111 // will return buffer with newly assigned |width| and |height|. When necessary,
112 // old buffer will be removed from the buffer queue and replaced with new buffer
113 // matching the new buffer size.
115 // @param write_queue The DvrWriteBufferQueue of interest.
116 // @param width Desired width, cannot be Zero.
117 // @param height Desired height, cannot be Zero.
118 // @return Zero on success, or negative error code.
119 int dvrWriteBufferQueueResizeBuffer(DvrWriteBufferQueue* write_queue,
120 uint32_t width, uint32_t height);
122 // Destroy a read buffer queue.
124 // @param read_queue The DvrReadBufferQueue of interest.
125 void dvrReadBufferQueueDestroy(DvrReadBufferQueue* read_queue);
127 // Get the total number of buffers in a read buffer queue.
129 // @param read_queue The DvrReadBufferQueue of interest.
130 // @return The capacity on success; or negative error code.
131 ssize_t dvrReadBufferQueueGetCapacity(DvrReadBufferQueue* read_queue);
133 // Get the system unique queue id of a read buffer queue.
135 // @param read_queue The DvrReadBufferQueue of interest.
136 // @return Queue id on success; or negative error code.
137 int dvrReadBufferQueueGetId(DvrReadBufferQueue* read_queue);
139 // Get the event fd that signals when queue updates occur.
141 // Use ReadBufferQueueHandleEvents to trigger registered event callbacks.
143 // @param read_queue The DvrReadBufferQueue of interest.
144 // @return Fd on success; or negative error code.
145 int dvrReadBufferQueueGetEventFd(DvrReadBufferQueue* read_queue);
147 // Create a read buffer queue from an existing read buffer queue.
149 // @param read_queue The DvrReadBufferQueue of interest.
150 // @param out_read_queue The pointer of a DvrReadBufferQueue will be filled here
151 // if the method call succeeds.
152 // @return Zero on success, or negative error code.
153 int dvrReadBufferQueueCreateReadQueue(DvrReadBufferQueue* read_queue,
154 DvrReadBufferQueue** out_read_queue);
156 // Dequeue a buffer to read from.
158 // @param read_queue The DvrReadBufferQueue of interest.
159 // @param timeout Specifies the number of milliseconds that the method will
160 // block. Specifying a timeout of -1 causes it to block indefinitely,
161 // while specifying a timeout equal to zero cause it to return immediately,
162 // even if no buffers are available.
163 // @param out_buffer A targeting DvrReadBuffer object to hold the output of the
164 // dequeue operation. Must be created by |dvrReadBufferCreateEmpty|.
165 // @param out_fence_fd A sync fence fd defined in NDK's sync.h API, which
166 // signals the release of underlying buffer. The consumer should wait until
167 // this fence clears before reading data from it.
168 // @param out_meta The memory area where a metadata object will be filled.
169 // Can be nullptr iff |meta_size_bytes| is zero (i.e., there is no
171 // @param meta_size_bytes Size of the metadata object caller expects. If it
172 // doesn't match the size of actually metadata transported by the buffer
173 // queue, the method returns -EINVAL.
174 // @return Zero on success, or negative error code.
175 int dvrReadBufferQueueDequeue(DvrReadBufferQueue* read_queue, int timeout,
176 DvrReadBuffer* out_buffer, int* out_fence_fd,
177 void* out_meta, size_t meta_size_bytes);
179 // Callback function which will be called when a buffer is avaiable.
181 // Note that there is no guarantee of thread safety and on which thread the
182 // callback will be fired.
184 // @param context User provided opaque pointer.
185 typedef void (*DvrReadBufferQueueBufferAvailableCallback)(void* context);
187 // Set buffer avaiable callback.
189 // @param read_queue The DvrReadBufferQueue of interest.
190 // @param callback The callback function. Set this to NULL if caller no longer
191 // needs to listen to new buffer available events.
192 // @param context User provided opaque pointer, will be passed back during
193 // callback. The caller is responsible for ensuring the validity of the
194 // context through the life cycle of the DvrReadBufferQueue.
195 // @return Zero on success, or negative error code.
196 int dvrReadBufferQueueSetBufferAvailableCallback(
197 DvrReadBufferQueue* read_queue,
198 DvrReadBufferQueueBufferAvailableCallback callback, void* context);
200 // Callback function which will be called when a buffer is about to be removed.
202 // Note that there is no guarantee of thread safety and on which thread the
203 // callback will be fired.
205 // @param buffer The buffer being removed. Once the callbacks returns, this
206 // buffer will be dereferenced from the buffer queue. If user has ever
207 // cached other DvrReadBuffer/AHardwareBuffer/EglImageKHR objects derived
208 // from this buffer, it's the user's responsibility to clean them up.
209 // Note that the ownership of the read buffer is not passed to this
210 // callback, so it should call dvrReadBufferDestroy on the buffer.
211 // @param context User provided opaque pointer.
212 typedef void (*DvrReadBufferQueueBufferRemovedCallback)(DvrReadBuffer* buffer,
215 // Set buffer removed callback.
217 // @param read_queue The DvrReadBufferQueue of interest.
218 // @param callback The callback function. Set this to NULL if caller no longer
219 // needs to listen to buffer removed events.
220 // @param context User provided opaque pointer, will be passed back during
221 // callback. The caller is responsible for ensuring the validity of the
222 // context through the life cycle of the DvrReadBufferQueue.
223 // @return Zero on success, or negative error code.
224 int dvrReadBufferQueueSetBufferRemovedCallback(
225 DvrReadBufferQueue* read_queue,
226 DvrReadBufferQueueBufferRemovedCallback callback, void* context);
228 // Handle all pending events on the read queue.
230 // @param read_queue The DvrReadBufferQueue of interest.
231 // @return Zero on success, or negative error code.
232 int dvrReadBufferQueueHandleEvents(DvrReadBufferQueue* read_queue);
236 #endif // ANDROID_DVR_BUFFER_QUEUE_H_