summaryrefslogtreecommitdiff
path: root/src/lib/ecore_buffer/Ecore_Buffer_Queue.h
blob: 4bc79ae60985e64c5880680029dd01a8954270c8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
#ifndef _ECORE_BUFFER_QUEUE_H_
#define _ECORE_BUFFER_QUEUE_H_

#ifdef EAPI
# undef EAPI
#endif

#ifdef _WIN32
# ifdef EFL_ECORE_BUFFER_BUILD
#  ifdef DLL_EXPORT
#   define EAPI __declspec(dllexport)
#  else
#   define EAPI
#  endif /* ! DLL_EXPORT */
# else
#  define EAPI __declspec(dllimport)
# endif /* ! EFL_ECORE_BUFFER_BUILD */
#else
# ifdef __GNUC__
#  if __GNUC__ >= 4
#   define EAPI __attribute__ ((visibility("default")))
#  else
#   define EAPI
#  endif
# else
#  define EAPI
# endif
#endif /* ! _WIN32 */

#ifdef __cplusplus
extern "C" {
#endif

#include <Eina.h>
#include "Ecore_Buffer.h"

/**
 * @defgroup Ecore_Buffer_Queue_Group Ecore Buffer Queue functions
 * @ingroup Ecore_Buffer_Group
 *
 * Ecore Buffer Queue is a queue which conntects processes for sharing
 * Ecore_Buffer.
 * one process (related object is Ecore_Buffer_Provider) has rear terminal
 * position of Ecore_Buffer Queue which can enqueue the Ecore_Buffer,
 * and the other process (related object is Ecore_Buffer_Consumer) has front
 * terminal position of Ecore_Buffer_Queue which can dequeue the Ecore_Buffer.
 */

/**
 * @defgroup Ecore_Buffer_Provider_Group Ecore Buffer Provider functions
 * @ingroup Ecore_Buffer_Queue_Group
 *
 * This group of functions is applied to an Ecore_Buffer_Provider object.
 * Ecore_Buffer_Provider provides Ecore_Buffer to Ecore_Buffer_Consumer(usually
 * different process or thread from Ecore_Buffer_Provider).
 * Ecore_Buffer_Provider should creates Ecore_Buffer as a provider.
 */

/**
 * @defgroup Ecore_Buffer_Consumer_Group Ecore Buffer Consumer functions
 * @ingroup Ecore_Buffer_Queue_Group
 *
 * This group of functions is applied to an Ecore_Buffer_Consumer object.
 * Ecore_Buffer_Consumer receives Ecore_Buffer enqueued by Ecore_Buffer_Provider.
 * Consumer must release Ecore_Buffer when it's no longer used.
 * Thus, the Ecore_Buffer_Provider is now free to re-use or destroy Ecore_Buffer.
 */

/**
 * @typedef Ecore_Buffer_Return
 * @enum _Ecore_Buffer_Return
 * types for an buffer queue state on provider side.
 * @ingroup Ecore_Buffer_Provider_Group
 * @see ecore_buffer_provider_buffer_acquire()
 * @see ecore_buffer_provider_buffer_acquirable_check()
 */
typedef enum _Ecore_Buffer_Return
{
   ECORE_BUFFER_RETURN_ERROR,       /**< on error @since 1.15 */
   ECORE_BUFFER_RETURN_SUCCESS,     /**< success to dequeue a buffer @since 1.15 */
   ECORE_BUFFER_RETURN_EMPTY,       /**< Empty queue @since 1.15 */
   ECORE_BUFFER_RETURN_NOT_EMPTY,   /**< Not empty queue @since 1.15 */
   ECORE_BUFFER_RETURN_NEED_ALLOC,  /**< need to create Ecore_Buffer @since 1.15 */
} Ecore_Buffer_Return;
/**
 * @typedef Ecore_Buffer_Consumer
 * An object representing a consumer of Ecore_Buffer.
 *
 * @since 1.15
 *
 * @ingroup Ecore_Buffer_Consumer_Group
 */
typedef struct _Ecore_Buffer_Consumer Ecore_Buffer_Consumer;
/**
 * @typedef Ecore_Buffer_Provider
 * An object representing a provider of Ecore_Buffer.
 *
 * @since 1.15
 *
 * @ingroup Ecore_Buffer_Provider_Group
 */
typedef struct _Ecore_Buffer_Provider Ecore_Buffer_Provider;
/**
 * @typedef Ecore_Buffer_Consumer_Provider_Add_Cb
 *
 * @brief Called whenever a Ecore_Buffer_Provider connected.
 *
 * @since 1.15
 *
 * @see ecore_buffer_consumer_provider_add_cb_set()
 * @ingroup Ecore_Buffer_Consumer_Group
 */
typedef void (*Ecore_Buffer_Consumer_Provider_Add_Cb) (Ecore_Buffer_Consumer *consumer, void *data);
/**
 * @typedef Ecore_Buffer_Consumer_Provider_Del_Cb
 *
 * @brief Called whenever a Ecore_Buffer_Provider disonnected.
 *
 * @since 1.15
 *
 * @see ecore_buffer_consumer_provider_del_cb_set()
 * @ingroup Ecore_Buffer_Consumer_Group
 */
typedef void (*Ecore_Buffer_Consumer_Provider_Del_Cb) (Ecore_Buffer_Consumer *consumer, void *data);
/**
 * @typedef Ecore_Buffer_Consumer_Enqueue_Cb
 *
 * @brief Called whenever a Ecore_Buffer enqueued in buffer queue.
 *
 * @since 1.15
 *
 * @see ecore_buffer_consumer_buffer_enqueued_cb_set()
 * @ingroup Ecore_Buffer_Consumer_Group
 */
typedef void (*Ecore_Buffer_Consumer_Enqueue_Cb) (Ecore_Buffer_Consumer *consumer, void *data);
/**
 * @typedef Ecore_Buffer_Provider_Consumer_Add_Cb
 *
 * @brief Called whenever a Ecore_Buffer_Consumer connected.
 *
 * @since 1.15
 *
 * @see ecore_buffer_provider_consumer_add_cb_set()
 * @ingroup Ecore_Buffer_Provider_Group
 */
typedef void (*Ecore_Buffer_Provider_Consumer_Add_Cb) (Ecore_Buffer_Provider *provider, int queue_size, int w, int h, void *data);
/**
 * @typedef Ecore_Buffer_Provider_Consumer_Del_Cb
 *
 * @brief Called whenever a Ecore_Buffer_Consumer disconnected.
 *
 * @since 1.15
 *
 * @see ecore_buffer_provider_consumer_del_cb_set()
 * @ingroup Ecore_Buffer_Provider_Group
 */
typedef void (*Ecore_Buffer_Provider_Consumer_Del_Cb) (Ecore_Buffer_Provider *provider, void *data);
/**
 * @typedef Ecore_Buffer_Provider_Enqueue_Cb
 *
 * @brief Called whenever a Ecore_Buffer is released.
 *
 * @since 1.15
 *
 * @see ecore_buffer_provider_buffer_released_cb_set()
 * @ingroup Ecore_Buffer_Provider_Group
 */
typedef void (*Ecore_Buffer_Provider_Enqueue_Cb) (Ecore_Buffer_Provider *provider, void *data);

/**
 * @addtogroup Ecore_Buffer_Queue_Group
 * @{
 */

/**
 * @brief Init the Ecore_Buffer_Queue system.
 *
 * @since 1.15
 *
 * @return How many times the lib has been initialized, 0 indicates failure.
 *
 * Set up the connection of Buffer Queue deamon, and Init Ecore_Buffer_Queue libraries.
 *
 * @see ecore_buffer_queue_shutdown()
 */
EAPI int   ecore_buffer_queue_init(void);
/**
 * @brief Shut down the Ecore_Buffer_Queue system.
 *
 * @since 1.15
 *
 * this closes the connection of Buffer Queue deamon, and Shut down Ecore_Buffer_Queue libraries.
 *
 * @see ecore_buffer_queue_init()
 */
EAPI int    ecore_buffer_queue_shutdown(void);

/**
 * @}
 */

/**
 * @addtogroup Ecore_Buffer_Consumer_Group
 * @{
 */

/**
 * @brief Creates a new Buffer Consumer based on name and common parameters.
 *
 * @since 1.15
 *
 * @param[in] name the name of Buffer_Queue, this is needed by Consumer and Provider to connect each other.
 * @param[in] queue_size size of Queue (If you pass this 0, then default size two(2) is appied)
 * @param[in] w width of buffer recommeneded to provider.
 * @param[in] h height of buffer recommended to provider.
 *
 * @return Ecore_Buffer_Consumer instance or @c NULL if creation failed.
 */
EAPI Ecore_Buffer_Consumer    *ecore_buffer_consumer_new(const char *name, int32_t queue_size, int32_t w, int32_t h);
/**
 * @brief Free an Ecore_Buffer_Consumer
 *
 * @since 1.15
 *
 * @param[in] consumer The Ecore_Buffer_Consumer to free
 *
 * This frees up any memory used by the Ecore_Buffer_Consumer.
 */
EAPI void                      ecore_buffer_consumer_free(Ecore_Buffer_Consumer *consumer);
/**
 * @brief Return the latest Ecore_Buffer submitted by provider.
 *
 * @since 1.15
 *
 * @param[in] consumer The Ecore_Buffer_Consumer to request for buffer
 *
 * @return Ecore_Buffer handle or NULL if acquirement failed.
 *
 * @see ecore_buffer_consumer_buffer_release()
 *
 * Consumer can store Ecore_Buffer submitted by Provider as much as size of queue
 * which is passed as a argument of ecore_buffer_consumer_new().
 */
EAPI Ecore_Buffer             *ecore_buffer_consumer_buffer_dequeue(Ecore_Buffer_Consumer *consumer);
/**
 * @brief Release the acquired Ecore_Buffer.
 *
 * @since 1.15
 *
 * @param[in] consumer The Ecore_Buffer_Consumer to request release buffer
 * @param[in] buffer The Ecore_Buffer to release
 *
 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
 *
 * @see ecore_buffer_consumer_buffer_dequeue()
 *
 * Consumer should release the Ecore_Buffer after acquiring and using it.
 * By doing release, Ecore_Buffer will be used by provider again,
 * or freed internally if Ecore_Buffer is not necessary anymore.
 * If not, the resource of Ecore_Buffer is continually owned by consumer until released.
 */
EAPI Eina_Bool                 ecore_buffer_consumer_buffer_release(Ecore_Buffer_Consumer *consumer, Ecore_Buffer *buffer);
/**
 * @brief Check if Queue of Ecore_Buffer is empty.
 *
 * @since 1.15
 *
 * @param[in] consumer The Ecore_Buffer_Consumer to query
 *
 * @return @c EINA_TRUE means queue is empty, @c EINA_FALSE otherwise.
 */
EAPI Eina_Bool                 ecore_buffer_consumer_queue_is_empty(Ecore_Buffer_Consumer *consumer);
/**
 * @brief Set a callback for provider connection events.
 *
 * @since 1.15
 *
 * @param[in] consumer The Ecore_Buffer_Consumer to set callbacks on
 * @param[in] func The function to call
 * @param[in] data A pointer to the user data to store.
 *
 * A call to this function will set a callback on an Ecore_Buffer_Consumer, causing
 * @p func to be called whenever @p consumer is connected with provider.
 */
EAPI void                      ecore_buffer_consumer_provider_add_cb_set(Ecore_Buffer_Consumer *consumer, Ecore_Buffer_Consumer_Provider_Add_Cb func, void *data);
/**
 * @brief Set a callback for provider disconnection events.
 *
 * @since 1.15
 *
 * @param[in] consumer The Ecore_Buffer_Consumer to set callbacks on
 * @param[in] func The function to call
 * @param[in] data A pointer to the user data to store.
 *
 * A call to this function will set a callback on an Ecore_Buffer_Consumer, causing
 * @p func to be called whenever @p consumer is disconnected with provider.
 */
EAPI void                      ecore_buffer_consumer_provider_del_cb_set(Ecore_Buffer_Consumer *consumer, Ecore_Buffer_Consumer_Provider_Del_Cb func, void *data);
/**
 * @brief Set a callback for enqueued buffer events.
 *
 * @since 1.15
 *
 * @param[in] consumer The Ecore_Buffer_Consumer to set callbacks on
 * @param[in] func The function to call
 * @param[in] data A pointer to the user data to store.
 *
 * A call to this function will set a callback on an Ecore_Buffer_Consumer, causing
 * @p func to be called whenever @p consumer has received buffer submitted from provider.
 *
 * You may success acuiqre Ecore_Buffer after this callback called.
 */
EAPI void                      ecore_buffer_consumer_buffer_enqueued_cb_set(Ecore_Buffer_Consumer *consumer, Ecore_Buffer_Consumer_Enqueue_Cb func, void *data);

/**
 * @}
 */

/**
 * @addtogroup Ecore_Buffer_Provider_Group
 * @{
 */

/**
 * @brief Creates a new Buffer Provider based on name.
 *
 * @since 1.15
 *
 * @param[in] name the name of Buffer_Queue.
 *
 * @return Ecore_Buffer_Provider instance or @c NULL if creation failed.
 */
EAPI Ecore_Buffer_Provider    *ecore_buffer_provider_new(const char *name);
/**
 * @brief Free an Ecore_Buffer_Provider
 *
 * @since 1.15
 *
 * @param[in] provider The Ecore_Buffer_Provider to free
 *
 * This frees up any memory used by the Ecore_Buffer_Provider.
 */
EAPI void                      ecore_buffer_provider_free(Ecore_Buffer_Provider *provider);
/**
 * @brief Return the Ecore_Buffer released by consumer or State of Queue.
 *
 * @since 1.15
 *
 * @param[in] provider The Ecore_Buffer_Provider to request for buffer
 * @param[out] ret_buf A Pointer to the Ecore_Buffer
 *
 * @return The enumeration of Ecore_Buffer_Return to indicate result of Dequeueing.
 *
 * This function gives you drawable buffer and inform you the state of Queue.
 * Each return value of enumeration has meaning as below.
 * @li ECORE_BUFFER_RETURN_ERROR, means error occurred.
 * @li ECORE_BUFFER_RETURN_SUCCESS, means success to dequeue, therefore ret_buf is valid.
 * @li ECORE_BUFFER_RETURN_EMPTY, means queue is empty, not available slot in Queue.
 *  in other words, there is no free drawable buffer in Queue.
 * @li ECORE_BUFFER_RETURN_NEED_ALLOC, means that there is available slot, but not allocated.
 *  so, You may create new Ecore_Buffer, and then just enqueue the Ecore_Buffer.
 *
 * @see ecore_buffer_new(), ecore_buffer_provider_buffer_enqueue()
 */
EAPI Ecore_Buffer_Return       ecore_buffer_provider_buffer_acquire(Ecore_Buffer_Provider *provider, Ecore_Buffer **ret_buf);
/**
 * @brief Submit the Ecore_Buffer to Consumer to request compositing.
 *
 * @since 1.15
 *
 * @param[in] provider The Ecore_Buffer_Provider connected with consumer.
 * @param[in] buffer The Ecore_Buffer to submit
 *
 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
 *
 * This function allow you to submit the Ecore_Buffer to consumer to request compositing.
 * And this will be success, in case only you submit dequeued Ecore_Buffer,
 * and new Ecore_Buffer after received return value of ECORE_BUFFER_RETURN_NEED_ALLOC by ecore_buffer_provider_buffer_acquire().
 *
 * @see ecore_buffer_new(), ecore_buffer_provider_buffer_dequeue()
 */
EAPI Eina_Bool                 ecore_buffer_provider_buffer_enqueue(Ecore_Buffer_Provider *provider, Ecore_Buffer *buffer);
/**
 * @brief Check if state of queue.
 *
 * @since 1.15
 *
 * @param[in] provider The Ecore_Buffer_Provider to query
 *
 * @li ECORE_BUFFER_RETURN_NOT_EMPTY, means there is a dequeueable Ecore_Buffer at least one.
 * @li ECORE_BUFFER_RETURN_EMPTY, means queue is empty, not available slot in Queue.
 *  in other words, there is no free drawable buffer in Queue.
 * @li ECORE_BUFFER_RETURN_NEED_ALLOC, means that there is available slot, but not allocated.
 *  so, You may create new Ecore_Buffer, and then just enqueue the Ecore_Buffer.
 *
 * @return @c EINA_TRUE means queue is empty, @c EINA_FALSE otherwise.
 */
EAPI Ecore_Buffer_Return       ecore_buffer_provider_buffer_acquirable_check(Ecore_Buffer_Provider *provider);
/**
 * @brief Set a callback for consumer connection events.
 *
 * @since 1.15
 *
 * @param[in] provider The Ecore_Buffer_Provider to set callbacks on
 * @param[in] func The function to call
 * @param[in] data A pointer to the user data to store.
 *
 * A call to this function will set a callback on an Ecore_Buffer_Provider, causing
 * @p func to be called whenever @p provider is connected with consumer.
 */
EAPI void                      ecore_buffer_provider_consumer_add_cb_set(Ecore_Buffer_Provider *provider, Ecore_Buffer_Provider_Consumer_Add_Cb func, void *data);
/**
 * @brief Set a callback for consumer disconnection events.
 *
 * @since 1.15
 *
 * @param[in] provider The Ecore_Buffer_Provider to set callbacks on
 * @param[in] func The function to call
 * @param[in] data A pointer to the user data to store.
 *
 * A call to this function will set a callback on an Ecore_Buffer_Provider, causing
 * @p func to be called whenever @p provider is disconnected with consumer.
 */
EAPI void                      ecore_buffer_provider_consumer_del_cb_set(Ecore_Buffer_Provider *provider, Ecore_Buffer_Provider_Consumer_Del_Cb func, void *data);
/**
 * @brief Set a callback for released buffer events.
 *
 * @since 1.15
 *
 * @param[in] provider The Ecore_Buffer_Provider to set callbacks on
 * @param[in] func The function to call
 * @param[in] data A pointer to the user data to store.
 *
 * A call to this function will set a callback on an Ecore_Buffer_Provider, causing
 * @p func to be called whenever @p provider has received Ecore_Buffer released from provider.
 *
 * You may success dequeue the Ecore_Buffer after this callback called.
 */
EAPI void                      ecore_buffer_provider_buffer_released_cb_set(Ecore_Buffer_Provider *provider, Ecore_Buffer_Provider_Enqueue_Cb func, void *data);

/**
 * @}
 */

#ifdef __cplusplus
}
#endif

#endif /* _ECORE_BUFFER_QUEUE_H_ */