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  */
155 int av_fifo_write_from_cb(AVFifo *f, AVFifoCB read_cb,
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  */
186 int av_fifo_read_to_cb(AVFifo *f, AVFifoCB write_cb,
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  * @}
244  */
245 
246 #endif /* AVUTIL_FIFO_H */
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_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
AVFifo::elem_size
size_t elem_size
Definition: fifo.c:38
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_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_read
int av_fifo_read(AVFifo *f, void *buf, size_t nb_elems)
Read data from a FIFO.
Definition: fifo.c:240
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
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
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
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
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:482
av_fifo_freep2
void av_fifo_freep2(AVFifo **f)
Free an AVFifo and reset pointer to NULL.
Definition: fifo.c:286
Generated on Thu Sep 26 2024 23:15:54 for FFmpeg by   doxygen 1.8.17