FFmpeg
fifo.h
Go to the documentation of this file.
1 /*
2  * This file is part of FFmpeg.
3  *
4  * FFmpeg is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2.1 of the License, or (at your option) any later version.
8  *
9  * FFmpeg is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with FFmpeg; if not, write to the Free Software
16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17  */
18 
19 /**
20  * @file
21  * @ingroup lavu_fifo
22  * A generic FIFO API
23  */
24 
25 #ifndef AVUTIL_FIFO_H
26 #define AVUTIL_FIFO_H
27 
28 #include <stddef.h>
29 #include <stdint.h>
30 
31 #include "attributes.h"
32 #include "version.h"
33 
34 /**
35  * @defgroup lavu_fifo AVFifo
36  * @ingroup lavu_data
37  *
38  * @{
39  * A generic FIFO API
40  */
41 
42 typedef struct AVFifo AVFifo;
43 
44 /**
45  * Callback for writing or reading from a FIFO, passed to (and invoked from) the
46  * av_fifo_*_cb() functions. It may be invoked multiple times from a single
47  * av_fifo_*_cb() call and may process less data than the maximum size indicated
48  * by nb_elems.
49  *
50  * @param opaque the opaque pointer provided to the av_fifo_*_cb() function
51  * @param buf the buffer for reading or writing the data, depending on which
52  * av_fifo_*_cb function is called
53  * @param nb_elems On entry contains the maximum number of elements that can be
54  * read from / written into buf. On success, the callback should
55  * update it to contain the number of elements actually written.
56  *
57  * @return 0 on success, a negative error code on failure (will be returned from
58  * the invoking av_fifo_*_cb() function)
59  */
60 typedef int AVFifoCB(void *opaque, void *buf, size_t *nb_elems);
61 
62 /**
63  * Automatically resize the FIFO on writes, so that the data fits. This
64  * automatic resizing happens up to a limit that can be modified with
65  * av_fifo_auto_grow_limit().
66  */
67 #define AV_FIFO_FLAG_AUTO_GROW (1 << 0)
68 
69 /**
70  * Allocate and initialize an AVFifo with a given element size.
71  *
72  * @param elems initial number of elements that can be stored in the FIFO
73  * @param elem_size Size in bytes of a single element. Further operations on
74  * the returned FIFO will implicitly use this element size.
75  * @param flags a combination of AV_FIFO_FLAG_*
76  *
77  * @return newly-allocated AVFifo on success, a negative error code on failure
78  */
79 AVFifo *av_fifo_alloc2(size_t elems, size_t elem_size,
80  unsigned int flags);
81 
82 /**
83  * @return Element size for FIFO operations. This element size is set at
84  * FIFO allocation and remains constant during its lifetime
85  */
86 size_t av_fifo_elem_size(const AVFifo *f);
87 
88 /**
89  * Set the maximum size (in elements) to which the FIFO can be resized
90  * automatically. Has no effect unless AV_FIFO_FLAG_AUTO_GROW is used.
91  */
92 void av_fifo_auto_grow_limit(AVFifo *f, size_t max_elems);
93 
94 /**
95  * @return number of elements available for reading from the given FIFO.
96  */
97 size_t av_fifo_can_read(const AVFifo *f);
98 
99 /**
100  * @return Number of elements that can be written into the given FIFO without
101  * growing it.
102  *
103  * In other words, this number of elements or less is guaranteed to fit
104  * into the FIFO. More data may be written when the
105  * AV_FIFO_FLAG_AUTO_GROW flag was specified at FIFO creation, but this
106  * may involve memory allocation, which can fail.
107  */
108 size_t av_fifo_can_write(const AVFifo *f);
109 
110 /**
111  * Enlarge an AVFifo.
112  *
113  * On success, the FIFO will be large enough to hold exactly
114  * inc + av_fifo_can_read() + av_fifo_can_write()
115  * elements. In case of failure, the old FIFO is kept unchanged.
116  *
117  * @param f AVFifo to resize
118  * @param inc number of elements to allocate for, in addition to the current
119  * allocated size
120  * @return a non-negative number on success, a negative error code on failure
121  */
122 int av_fifo_grow2(AVFifo *f, size_t inc);
123 
124 /**
125  * Write data into a FIFO.
126  *
127  * In case nb_elems > av_fifo_can_write(f) and the AV_FIFO_FLAG_AUTO_GROW flag
128  * was not specified at FIFO creation, nothing is written and an error
129  * is returned.
130  *
131  * Calling function is guaranteed to succeed if nb_elems <= av_fifo_can_write(f).
132  *
133  * @param f the FIFO buffer
134  * @param buf Data to be written. nb_elems * av_fifo_elem_size(f) bytes will be
135  * read from buf on success.
136  * @param nb_elems number of elements to write into FIFO
137  *
138  * @return a non-negative number on success, a negative error code on failure
139  */
140 int av_fifo_write(AVFifo *f, const void *buf, size_t nb_elems);
141 
142 /**
143  * Write data from a user-provided callback into a FIFO.
144  *
145  * @param f the FIFO buffer
146  * @param read_cb Callback supplying the data to the FIFO. May be called
147  * multiple times.
148  * @param opaque opaque user data to be provided to read_cb
149  * @param nb_elems Should point to the maximum number of elements that can be
150  * written. Will be updated to contain the number of elements
151  * actually written.
152  *
153  * @return non-negative number on success, a negative error code on failure
154  */
156  void *opaque, size_t *nb_elems);
157 
158 /**
159  * Read data from a FIFO.
160  *
161  * In case nb_elems > av_fifo_can_read(f), nothing is read and an error
162  * is returned.
163  *
164  * @param f the FIFO buffer
165  * @param buf Buffer to store the data. nb_elems * av_fifo_elem_size(f) bytes
166  * will be written into buf on success.
167  * @param nb_elems number of elements to read from FIFO
168  *
169  * @return a non-negative number on success, a negative error code on failure
170  */
171 int av_fifo_read(AVFifo *f, void *buf, size_t nb_elems);
172 
173 /**
174  * Feed data from a FIFO into a user-provided callback.
175  *
176  * @param f the FIFO buffer
177  * @param write_cb Callback the data will be supplied to. May be called
178  * multiple times.
179  * @param opaque opaque user data to be provided to write_cb
180  * @param nb_elems Should point to the maximum number of elements that can be
181  * read. Will be updated to contain the total number of elements
182  * actually sent to the callback.
183  *
184  * @return non-negative number on success, a negative error code on failure
185  */
187  void *opaque, size_t *nb_elems);
188 
189 /**
190  * Read data from a FIFO without modifying FIFO state.
191  *
192  * Returns an error if an attempt is made to peek to nonexistent elements
193  * (i.e. if offset + nb_elems is larger than av_fifo_can_read(f)).
194  *
195  * @param f the FIFO buffer
196  * @param buf Buffer to store the data. nb_elems * av_fifo_elem_size(f) bytes
197  * will be written into buf.
198  * @param nb_elems number of elements to read from FIFO
199  * @param offset number of initial elements to skip.
200  *
201  * @return a non-negative number on success, a negative error code on failure
202  */
203 int av_fifo_peek(const AVFifo *f, void *buf, size_t nb_elems, size_t offset);
204 
205 /**
206  * Feed data from a FIFO into a user-provided callback.
207  *
208  * @param f the FIFO buffer
209  * @param write_cb Callback the data will be supplied to. May be called
210  * multiple times.
211  * @param opaque opaque user data to be provided to write_cb
212  * @param nb_elems Should point to the maximum number of elements that can be
213  * read. Will be updated to contain the total number of elements
214  * actually sent to the callback.
215  * @param offset number of initial elements to skip; offset + *nb_elems must not
216  * be larger than av_fifo_can_read(f).
217  *
218  * @return a non-negative number on success, a negative error code on failure
219  */
220 int av_fifo_peek_to_cb(const AVFifo *f, AVFifoCB write_cb, void *opaque,
221  size_t *nb_elems, size_t offset);
222 
223 /**
224  * Discard the specified amount of data from an AVFifo.
225  * @param size number of elements to discard, MUST NOT be larger than
226  * av_fifo_can_read(f)
227  */
228 void av_fifo_drain2(AVFifo *f, size_t size);
229 
230 /*
231  * Empty the AVFifo.
232  * @param f AVFifo to reset
233  */
234 void av_fifo_reset2(AVFifo *f);
235 
236 /**
237  * Free an AVFifo and reset pointer to NULL.
238  * @param f Pointer to an AVFifo to free. *f == NULL is allowed.
239  */
240 void av_fifo_freep2(AVFifo **f);
241 
242 
243 #if FF_API_FIFO_OLD_API
244 typedef struct AVFifoBuffer {
245  uint8_t *buffer;
246  uint8_t *rptr, *wptr, *end;
247  uint32_t rndx, wndx;
248 } AVFifoBuffer;
249 
250 /**
251  * Initialize an AVFifoBuffer.
252  * @param size of FIFO
253  * @return AVFifoBuffer or NULL in case of memory allocation failure
254  * @deprecated use av_fifo_alloc2()
255  */
257 AVFifoBuffer *av_fifo_alloc(unsigned int size);
258 
259 /**
260  * Initialize an AVFifoBuffer.
261  * @param nmemb number of elements
262  * @param size size of the single element
263  * @return AVFifoBuffer or NULL in case of memory allocation failure
264  * @deprecated use av_fifo_alloc2()
265  */
267 AVFifoBuffer *av_fifo_alloc_array(size_t nmemb, size_t size);
268 
269 /**
270  * Free an AVFifoBuffer.
271  * @param f AVFifoBuffer to free
272  * @deprecated use the AVFifo API with av_fifo_freep2()
273  */
276 
277 /**
278  * Free an AVFifoBuffer and reset pointer to NULL.
279  * @param f AVFifoBuffer to free
280  * @deprecated use the AVFifo API with av_fifo_freep2()
281  */
284 
285 /**
286  * Reset the AVFifoBuffer to the state right after av_fifo_alloc, in particular it is emptied.
287  * @param f AVFifoBuffer to reset
288  * @deprecated use av_fifo_reset2() with the new AVFifo-API
289  */
292 
293 /**
294  * Return the amount of data in bytes in the AVFifoBuffer, that is the
295  * amount of data you can read from it.
296  * @param f AVFifoBuffer to read from
297  * @return size
298  * @deprecated use av_fifo_can_read() with the new AVFifo-API
299  */
301 int av_fifo_size(const AVFifoBuffer *f);
302 
303 /**
304  * Return the amount of space in bytes in the AVFifoBuffer, that is the
305  * amount of data you can write into it.
306  * @param f AVFifoBuffer to write into
307  * @return size
308  * @deprecated use av_fifo_can_write() with the new AVFifo-API
309  */
311 int av_fifo_space(const AVFifoBuffer *f);
312 
313 /**
314  * Feed data at specific position from an AVFifoBuffer to a user-supplied callback.
315  * Similar as av_fifo_gereric_read but without discarding data.
316  * @param f AVFifoBuffer to read from
317  * @param offset offset from current read position
318  * @param buf_size number of bytes to read
319  * @param func generic read function
320  * @param dest data destination
321  *
322  * @return a non-negative number on success, a negative error code on failure
323  *
324  * @deprecated use the new AVFifo-API with av_fifo_peek() when func == NULL,
325  * av_fifo_peek_to_cb() otherwise
326  */
328 int av_fifo_generic_peek_at(AVFifoBuffer *f, void *dest, int offset, int buf_size, void (*func)(void*, void*, int));
329 
330 /**
331  * Feed data from an AVFifoBuffer to a user-supplied callback.
332  * Similar as av_fifo_gereric_read but without discarding data.
333  * @param f AVFifoBuffer to read from
334  * @param buf_size number of bytes to read
335  * @param func generic read function
336  * @param dest data destination
337  *
338  * @return a non-negative number on success, a negative error code on failure
339  *
340  * @deprecated use the new AVFifo-API with av_fifo_peek() when func == NULL,
341  * av_fifo_peek_to_cb() otherwise
342  */
344 int av_fifo_generic_peek(AVFifoBuffer *f, void *dest, int buf_size, void (*func)(void*, void*, int));
345 
346 /**
347  * Feed data from an AVFifoBuffer to a user-supplied callback.
348  * @param f AVFifoBuffer to read from
349  * @param buf_size number of bytes to read
350  * @param func generic read function
351  * @param dest data destination
352  *
353  * @return a non-negative number on success, a negative error code on failure
354  *
355  * @deprecated use the new AVFifo-API with av_fifo_read() when func == NULL,
356  * av_fifo_read_to_cb() otherwise
357  */
359 int av_fifo_generic_read(AVFifoBuffer *f, void *dest, int buf_size, void (*func)(void*, void*, int));
360 
361 /**
362  * Feed data from a user-supplied callback to an AVFifoBuffer.
363  * @param f AVFifoBuffer to write to
364  * @param src data source; non-const since it may be used as a
365  * modifiable context by the function defined in func
366  * @param size number of bytes to write
367  * @param func generic write function; the first parameter is src,
368  * the second is dest_buf, the third is dest_buf_size.
369  * func must return the number of bytes written to dest_buf, or <= 0 to
370  * indicate no more data available to write.
371  * If func is NULL, src is interpreted as a simple byte array for source data.
372  * @return the number of bytes written to the FIFO or a negative error code on failure
373  *
374  * @deprecated use the new AVFifo-API with av_fifo_write() when func == NULL,
375  * av_fifo_write_from_cb() otherwise
376  */
378 int av_fifo_generic_write(AVFifoBuffer *f, void *src, int size, int (*func)(void*, void*, int));
379 
380 /**
381  * Resize an AVFifoBuffer.
382  * In case of reallocation failure, the old FIFO is kept unchanged.
383  *
384  * @param f AVFifoBuffer to resize
385  * @param size new AVFifoBuffer size in bytes
386  * @return <0 for failure, >=0 otherwise
387  *
388  * @deprecated use the new AVFifo-API with av_fifo_grow2() to increase FIFO size,
389  * decreasing FIFO size is not supported
390  */
392 int av_fifo_realloc2(AVFifoBuffer *f, unsigned int size);
393 
394 /**
395  * Enlarge an AVFifoBuffer.
396  * In case of reallocation failure, the old FIFO is kept unchanged.
397  * The new fifo size may be larger than the requested size.
398  *
399  * @param f AVFifoBuffer to resize
400  * @param additional_space the amount of space in bytes to allocate in addition to av_fifo_size()
401  * @return <0 for failure, >=0 otherwise
402  *
403  * @deprecated use the new AVFifo-API with av_fifo_grow2(); note that unlike
404  * this function it adds to the allocated size, rather than to the used size
405  */
407 int av_fifo_grow(AVFifoBuffer *f, unsigned int additional_space);
408 
409 /**
410  * Read and discard the specified amount of data from an AVFifoBuffer.
411  * @param f AVFifoBuffer to read from
412  * @param size amount of data to read in bytes
413  *
414  * @deprecated use the new AVFifo-API with av_fifo_drain2()
415  */
417 void av_fifo_drain(AVFifoBuffer *f, int size);
418 
419 #if FF_API_FIFO_PEEK2
420 /**
421  * Return a pointer to the data stored in a FIFO buffer at a certain offset.
422  * The FIFO buffer is not modified.
423  *
424  * @param f AVFifoBuffer to peek at, f must be non-NULL
425  * @param offs an offset in bytes, its absolute value must be less
426  * than the used buffer size or the returned pointer will
427  * point outside to the buffer data.
428  * The used buffer size can be checked with av_fifo_size().
429  * @deprecated use the new AVFifo-API with av_fifo_peek() or av_fifo_peek_to_cb()
430  */
432 static inline uint8_t *av_fifo_peek2(const AVFifoBuffer *f, int offs)
433 {
434  uint8_t *ptr = f->rptr + offs;
435  if (ptr >= f->end)
436  ptr = f->buffer + (ptr - f->end);
437  else if (ptr < f->buffer)
438  ptr = f->end - (f->buffer - ptr);
439  return ptr;
440 }
441 #endif
442 #endif
443 
444 /**
445  * @}
446  */
447 
448 #endif /* AVUTIL_FIFO_H */
av_fifo_alloc_array
attribute_deprecated AVFifoBuffer * av_fifo_alloc_array(size_t nmemb, size_t size)
Initialize an AVFifoBuffer.
Definition: fifo.c:300
func
int(* func)(AVBPrint *dst, const char *in, const char *arg)
Definition: jacosubdec.c:68
av_fifo_drain2
void av_fifo_drain2(AVFifo *f, size_t size)
Discard the specified amount of data from an AVFifo.
Definition: fifo.c:266
av_fifo_can_write
size_t av_fifo_can_write(const AVFifo *f)
Definition: fifo.c:94
av_fifo_freep
attribute_deprecated void av_fifo_freep(AVFifoBuffer **f)
Free an AVFifoBuffer and reset pointer to NULL.
Definition: fifo.c:335
av_fifo_peek_to_cb
int av_fifo_peek_to_cb(const AVFifo *f, AVFifoCB write_cb, void *opaque, size_t *nb_elems, size_t offset)
Feed data from a FIFO into a user-provided callback.
Definition: fifo.c:260
av_fifo_free
attribute_deprecated void av_fifo_free(AVFifoBuffer *f)
Free an AVFifoBuffer.
Definition: fifo.c:327
AVFifo::elem_size
size_t elem_size
Definition: fifo.c:38
AVFifoBuffer::wptr
uint8_t * wptr
Definition: fifo.h:246
av_fifo_peek
int av_fifo_peek(const AVFifo *f, void *buf, size_t nb_elems, size_t offset)
Read data from a FIFO without modifying FIFO state.
Definition: fifo.c:255
av_fifo_auto_grow_limit
void av_fifo_auto_grow_limit(AVFifo *f, size_t max_elems)
Set the maximum size (in elements) to which the FIFO can be resized automatically.
Definition: fifo.c:77
av_fifo_drain
attribute_deprecated void av_fifo_drain(AVFifoBuffer *f, int size)
Read and discard the specified amount of data from an AVFifoBuffer.
Definition: fifo.c:502
AVFifoBuffer
Definition: fifo.h:244
av_fifo_write
int av_fifo_write(AVFifo *f, const void *buf, size_t nb_elems)
Write data into a FIFO.
Definition: fifo.c:188
av_fifo_grow2
int av_fifo_grow2(AVFifo *f, size_t inc)
Enlarge an AVFifo.
Definition: fifo.c:99
AVFifoCB
int AVFifoCB(void *opaque, void *buf, size_t *nb_elems)
Callback for writing or reading from a FIFO, passed to (and invoked from) the av_fifo_*_cb() function...
Definition: fifo.h:60
av_fifo_realloc2
attribute_deprecated int av_fifo_realloc2(AVFifoBuffer *f, unsigned int size)
Resize an AVFifoBuffer.
Definition: fifo.c:359
av_fifo_read
int av_fifo_read(AVFifo *f, void *buf, size_t nb_elems)
Read data from a FIFO.
Definition: fifo.c:240
av_fifo_generic_write
attribute_deprecated int av_fifo_generic_write(AVFifoBuffer *f, void *src, int size, int(*func)(void *, void *, int))
Feed data from a user-supplied callback to an AVFifoBuffer.
Definition: fifo.c:411
av_fifo_generic_peek
attribute_deprecated int av_fifo_generic_peek(AVFifoBuffer *f, void *dest, int buf_size, void(*func)(void *, void *, int))
Feed data from an AVFifoBuffer to a user-supplied callback.
Definition: fifo.c:475
av_fifo_grow
attribute_deprecated int av_fifo_grow(AVFifoBuffer *f, unsigned int additional_space)
Enlarge an AVFifoBuffer.
Definition: fifo.c:396
av_fifo_write_from_cb
int av_fifo_write_from_cb(AVFifo *f, AVFifoCB read_cb, void *opaque, size_t *nb_elems)
Write data from a user-provided callback into a FIFO.
Definition: fifo.c:193
AVFifoBuffer::end
uint8_t * end
Definition: fifo.h:246
av_fifo_can_read
size_t av_fifo_can_read(const AVFifo *f)
Definition: fifo.c:87
av_fifo_elem_size
size_t av_fifo_elem_size(const AVFifo *f)
Definition: fifo.c:82
av_fifo_reset2
void av_fifo_reset2(AVFifo *f)
Definition: fifo.c:280
f
f
Definition: af_crystalizer.c:121
av_fifo_read_to_cb
int av_fifo_read_to_cb(AVFifo *f, AVFifoCB write_cb, void *opaque, size_t *nb_elems)
Feed data from a FIFO into a user-provided callback.
Definition: fifo.c:247
AVFifo
Definition: fifo.c:35
AVFifo::nb_elems
size_t nb_elems
Definition: fifo.c:38
read_cb
static int read_cb(void *opaque, void *buf, size_t *nb_elems)
Definition: fifo.c:33
size
int size
Definition: twinvq_data.h:10344
av_fifo_peek2
static attribute_deprecated uint8_t * av_fifo_peek2(const AVFifoBuffer *f, int offs)
Return a pointer to the data stored in a FIFO buffer at a certain offset.
Definition: fifo.h:432
attribute_deprecated
#define attribute_deprecated
Definition: attributes.h:104
offset
it s the only field you need to keep assuming you have a context There is some magic you don t need to care about around this just let it vf offset
Definition: writing_filters.txt:86
attributes.h
AVFifoBuffer::buffer
uint8_t * buffer
Definition: fifo.h:245
AVFifoBuffer::wndx
uint32_t wndx
Definition: fifo.h:247
version.h
av_fifo_alloc2
AVFifo * av_fifo_alloc2(size_t elems, size_t elem_size, unsigned int flags)
Allocate and initialize an AVFifo with a given element size.
Definition: fifo.c:47
av_fifo_size
attribute_deprecated int av_fifo_size(const AVFifoBuffer *f)
Return the amount of data in bytes in the AVFifoBuffer, that is the amount of data you can read from ...
Definition: fifo.c:349
av_fifo_alloc
attribute_deprecated AVFifoBuffer * av_fifo_alloc(unsigned int size)
Initialize an AVFifoBuffer.
Definition: fifo.c:322
buffer
the frame and frame reference mechanism is intended to as much as expensive copies of that data while still allowing the filters to produce correct results The data is stored in buffers represented by AVFrame structures Several references can point to the same frame buffer
Definition: filter_design.txt:49
av_fifo_reset
attribute_deprecated void av_fifo_reset(AVFifoBuffer *f)
Reset the AVFifoBuffer to the state right after av_fifo_alloc, in particular it is emptied.
Definition: fifo.c:343
av_fifo_space
attribute_deprecated int av_fifo_space(const AVFifoBuffer *f)
Return the amount of space in bytes in the AVFifoBuffer, that is the amount of data you can write int...
Definition: fifo.c:354
src
INIT_CLIP pixel * src
Definition: h264pred_template.c:418
av_fifo_generic_read
attribute_deprecated int av_fifo_generic_read(AVFifoBuffer *f, void *dest, int buf_size, void(*func)(void *, void *, int))
Feed data from an AVFifoBuffer to a user-supplied callback.
Definition: fifo.c:481
AVFifoBuffer::rptr
uint8_t * rptr
Definition: fifo.h:246
write_cb
static int write_cb(void *opaque, void *buf, size_t *nb_elems)
Definition: fifo.c:53
flags
#define flags(name, subs,...)
Definition: cbs_av1.c:474
av_fifo_freep2
void av_fifo_freep2(AVFifo **f)
Free an AVFifo and reset pointer to NULL.
Definition: fifo.c:286
AVFifoBuffer::rndx
uint32_t rndx
Definition: fifo.h:247
av_fifo_generic_peek_at
attribute_deprecated int av_fifo_generic_peek_at(AVFifoBuffer *f, void *dest, int offset, int buf_size, void(*func)(void *, void *, int))
Feed data at specific position from an AVFifoBuffer to a user-supplied callback.
Definition: fifo.c:442