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 
30 /**
31  * @defgroup lavu_fifo AVFifo
32  * @ingroup lavu_data
33  *
34  * @{
35  * A generic FIFO API
36  */
37 
38 typedef struct AVFifo AVFifo;
39 
40 /**
41  * Callback for writing or reading from a FIFO, passed to (and invoked from) the
42  * av_fifo_*_cb() functions. It may be invoked multiple times from a single
43  * av_fifo_*_cb() call and may process less data than the maximum size indicated
44  * by nb_elems.
45  *
46  * @param opaque the opaque pointer provided to the av_fifo_*_cb() function
47  * @param buf the buffer for reading or writing the data, depending on which
48  * av_fifo_*_cb function is called
49  * @param nb_elems On entry contains the maximum number of elements that can be
50  * read from / written into buf. On success, the callback should
51  * update it to contain the number of elements actually written.
52  *
53  * @return 0 on success, a negative error code on failure (will be returned from
54  * the invoking av_fifo_*_cb() function)
55  */
56 typedef int AVFifoCB(void *opaque, void *buf, size_t *nb_elems);
57 
58 /**
59  * Automatically resize the FIFO on writes, so that the data fits. This
60  * automatic resizing happens up to a limit that can be modified with
61  * av_fifo_auto_grow_limit().
62  */
63 #define AV_FIFO_FLAG_AUTO_GROW (1 << 0)
64 
65 /**
66  * Allocate and initialize an AVFifo with a given element size.
67  *
68  * @param elems initial number of elements that can be stored in the FIFO
69  * @param elem_size Size in bytes of a single element. Further operations on
70  * the returned FIFO will implicitly use this element size.
71  * @param flags a combination of AV_FIFO_FLAG_*
72  *
73  * @return newly-allocated AVFifo on success, a negative error code on failure
74  */
75 AVFifo *av_fifo_alloc2(size_t elems, size_t elem_size,
76  unsigned int flags);
77 
78 /**
79  * @return Element size for FIFO operations. This element size is set at
80  * FIFO allocation and remains constant during its lifetime
81  */
82 size_t av_fifo_elem_size(const AVFifo *f);
83 
84 /**
85  * Set the maximum size (in elements) to which the FIFO can be resized
86  * automatically. Has no effect unless AV_FIFO_FLAG_AUTO_GROW is used.
87  */
88 void av_fifo_auto_grow_limit(AVFifo *f, size_t max_elems);
89 
90 /**
91  * @return number of elements available for reading from the given FIFO.
92  */
93 size_t av_fifo_can_read(const AVFifo *f);
94 
95 /**
96  * @return Number of elements that can be written into the given FIFO without
97  * growing it.
98  *
99  * In other words, this number of elements or less is guaranteed to fit
100  * into the FIFO. More data may be written when the
101  * AV_FIFO_FLAG_AUTO_GROW flag was specified at FIFO creation, but this
102  * may involve memory allocation, which can fail.
103  */
104 size_t av_fifo_can_write(const AVFifo *f);
105 
106 /**
107  * Enlarge an AVFifo.
108  *
109  * On success, the FIFO will be large enough to hold exactly
110  * inc + av_fifo_can_read() + av_fifo_can_write()
111  * elements. In case of failure, the old FIFO is kept unchanged.
112  *
113  * @param f AVFifo to resize
114  * @param inc number of elements to allocate for, in addition to the current
115  * allocated size
116  * @return a non-negative number on success, a negative error code on failure
117  */
118 int av_fifo_grow2(AVFifo *f, size_t inc);
119 
120 /**
121  * Write data into a FIFO.
122  *
123  * In case nb_elems > av_fifo_can_write(f) and the AV_FIFO_FLAG_AUTO_GROW flag
124  * was not specified at FIFO creation, nothing is written and an error
125  * is returned.
126  *
127  * Calling function is guaranteed to succeed if nb_elems <= av_fifo_can_write(f).
128  *
129  * @param f the FIFO buffer
130  * @param buf Data to be written. nb_elems * av_fifo_elem_size(f) bytes will be
131  * read from buf on success.
132  * @param nb_elems number of elements to write into FIFO
133  *
134  * @return a non-negative number on success, a negative error code on failure
135  */
136 int av_fifo_write(AVFifo *f, const void *buf, size_t nb_elems);
137 
138 /**
139  * Write data from a user-provided callback into a FIFO.
140  *
141  * @param f the FIFO buffer
142  * @param read_cb Callback supplying the data to the FIFO. May be called
143  * multiple times.
144  * @param opaque opaque user data to be provided to read_cb
145  * @param nb_elems Should point to the maximum number of elements that can be
146  * written. Will be updated to contain the number of elements
147  * actually written.
148  *
149  * @return non-negative number on success, a negative error code on failure
150  */
151 int av_fifo_write_from_cb(AVFifo *f, AVFifoCB read_cb,
152  void *opaque, size_t *nb_elems);
153 
154 /**
155  * Read data from a FIFO.
156  *
157  * In case nb_elems > av_fifo_can_read(f), nothing is read and an error
158  * is returned.
159  *
160  * @param f the FIFO buffer
161  * @param buf Buffer to store the data. nb_elems * av_fifo_elem_size(f) bytes
162  * will be written into buf on success.
163  * @param nb_elems number of elements to read from FIFO
164  *
165  * @return a non-negative number on success, a negative error code on failure
166  */
167 int av_fifo_read(AVFifo *f, void *buf, size_t nb_elems);
168 
169 /**
170  * Feed data from a FIFO into a user-provided callback.
171  *
172  * @param f the FIFO buffer
173  * @param write_cb Callback the data will be supplied to. May be called
174  * multiple times.
175  * @param opaque opaque user data to be provided to write_cb
176  * @param nb_elems Should point to the maximum number of elements that can be
177  * read. Will be updated to contain the total number of elements
178  * actually sent to the callback.
179  *
180  * @return non-negative number on success, a negative error code on failure
181  */
182 int av_fifo_read_to_cb(AVFifo *f, AVFifoCB write_cb,
183  void *opaque, size_t *nb_elems);
184 
185 /**
186  * Read data from a FIFO without modifying FIFO state.
187  *
188  * Returns an error if an attempt is made to peek to nonexistent elements
189  * (i.e. if offset + nb_elems is larger than av_fifo_can_read(f)).
190  *
191  * @param f the FIFO buffer
192  * @param buf Buffer to store the data. nb_elems * av_fifo_elem_size(f) bytes
193  * will be written into buf.
194  * @param nb_elems number of elements to read from FIFO
195  * @param offset number of initial elements to skip.
196  *
197  * @return a non-negative number on success, a negative error code on failure
198  */
199 int av_fifo_peek(const AVFifo *f, void *buf, size_t nb_elems, size_t offset);
200 
201 /**
202  * Feed data from a FIFO into a user-provided callback.
203  *
204  * @param f the FIFO buffer
205  * @param write_cb Callback the data will be supplied to. May be called
206  * multiple times.
207  * @param opaque opaque user data to be provided to write_cb
208  * @param nb_elems Should point to the maximum number of elements that can be
209  * read. Will be updated to contain the total number of elements
210  * actually sent to the callback.
211  * @param offset number of initial elements to skip; offset + *nb_elems must not
212  * be larger than av_fifo_can_read(f).
213  *
214  * @return a non-negative number on success, a negative error code on failure
215  */
216 int av_fifo_peek_to_cb(const AVFifo *f, AVFifoCB write_cb, void *opaque,
217  size_t *nb_elems, size_t offset);
218 
219 /**
220  * Discard the specified amount of data from an AVFifo.
221  * @param size number of elements to discard, MUST NOT be larger than
222  * av_fifo_can_read(f)
223  */
224 void av_fifo_drain2(AVFifo *f, size_t size);
225 
226 /*
227  * Empty the AVFifo.
228  * @param f AVFifo to reset
229  */
230 void av_fifo_reset2(AVFifo *f);
231 
232 /**
233  * Free an AVFifo and reset pointer to NULL.
234  * @param f Pointer to an AVFifo to free. *f == NULL is allowed.
235  */
236 void av_fifo_freep2(AVFifo **f);
237 
238 /**
239  * @}
240  */
241 
242 #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:56
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
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:474
av_fifo_freep2
void av_fifo_freep2(AVFifo **f)
Free an AVFifo and reset pointer to NULL.
Definition: fifo.c:286
Generated on Fri Apr 19 2024 19:22:52 for FFmpeg by   doxygen 1.8.17