FFmpeg
framequeue.h
Go to the documentation of this file.
1 /*
2  * Generic frame queue
3  * Copyright (c) 2016 Nicolas George
4  *
5  * This file is part of FFmpeg.
6  *
7  * FFmpeg is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public License
9  * as published by the Free Software Foundation; either
10  * version 2.1 of the License, or (at your option) any later version.
11  *
12  * FFmpeg is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15  * GNU Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public License
18  * along with FFmpeg; if not, write to the Free Software Foundation, Inc.,
19  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20  */
21 
22 #ifndef AVFILTER_FRAMEQUEUE_H
23 #define AVFILTER_FRAMEQUEUE_H
24 
25 /**
26  * FFFrameQueue: simple AVFrame queue API
27  *
28  * Note: this API is not thread-safe. Concurrent access to the same queue
29  * must be protected by a mutex or any synchronization mechanism.
30  */
31 
32 #include "libavutil/frame.h"
33 
34 typedef struct FFFrameBucket {
37 
38 /**
39  * Structure to hold global options and statistics for frame queues.
40  *
41  * This structure is intended to allow implementing global control of the
42  * frame queues, including memory consumption caps.
43  */
44 typedef struct FFFrameQueueGlobal {
45 
46  /**
47  * Maximum number of allowed frames in the queues combined.
48  */
49  size_t max_queued;
50 
51  /**
52  * Total number of queued frames in the queues combined.
53  */
54  size_t queued;
56 
57 /**
58  * Queue of AVFrame pointers.
59  */
60 typedef struct FFFrameQueue {
61 
62  /**
63  * Pointer to the global frame queue struct holding statistics and limits
64  */
66 
67  /**
68  * Array of allocated buckets, used as a circular buffer.
69  */
71 
72  /**
73  * Size of the array of buckets.
74  */
75  size_t allocated;
76 
77  /**
78  * Tail of the queue.
79  * It is the index in the array of the next frame to take.
80  */
81  size_t tail;
82 
83  /**
84  * Number of currently queued frames.
85  */
86  size_t queued;
87 
88  /**
89  * Pre-allocated bucket for queues of size 1.
90  */
92 
93  /**
94  * Total number of frames entered in the queue.
95  */
97 
98  /**
99  * Total number of frames dequeued from the queue.
100  * queued = total_frames_head - total_frames_tail
101  */
103 
104  /**
105  * Total number of samples entered in the queue.
106  */
108 
109  /**
110  * Total number of samples dequeued from the queue.
111  * queued_samples = total_samples_head - total_samples_tail
112  */
114 
115  /**
116  * Indicate that samples are skipped
117  */
119 
120 } FFFrameQueue;
121 
122 /**
123  * Init a global structure.
124  */
126 
127 /**
128  * Init a frame queue and attach it to a global structure.
129  */
131 
132 /**
133  * Free the queue and all queued frames.
134  */
136 
137 /**
138  * Add a frame.
139  * @return >=0 or an AVERROR code.
140  */
142 
143 /**
144  * Take the first frame in the queue.
145  * Must not be used with empty queues.
146  */
148 
149 /**
150  * Access a frame in the queue, without removing it.
151  * The first frame is numbered 0; the designated frame must exist.
152  */
153 AVFrame *ff_framequeue_peek(FFFrameQueue *fq, size_t idx);
154 
155 /**
156  * Get the number of queued frames.
157  */
158 static inline size_t ff_framequeue_queued_frames(const FFFrameQueue *fq)
159 {
160  return fq->queued;
161 }
162 
163 /**
164  * Get the number of queued samples.
165  */
166 static inline uint64_t ff_framequeue_queued_samples(const FFFrameQueue *fq)
167 {
168  return fq->total_samples_head - fq->total_samples_tail;
169 }
170 
171 /**
172  * Update the statistics after a frame accessed using ff_framequeue_peek()
173  * was modified.
174  * Currently used only as a marker.
175  */
176 static inline void ff_framequeue_update_peeked(FFFrameQueue *fq, size_t idx)
177 {
178 }
179 
180 /**
181  * Skip samples from the first frame in the queue.
182  *
183  * This function must be used when the first frame was accessed using
184  * ff_framequeue_peek() and samples were consumed from it.
185  * It adapts the data pointers and timestamps of the head frame to account
186  * for the skipped samples.
187  */
188 void ff_framequeue_skip_samples(FFFrameQueue *fq, size_t samples, AVRational time_base);
189 
190 #endif /* AVFILTER_FRAMEQUEUE_H */
FFFrameQueue::first_bucket
FFFrameBucket first_bucket
Pre-allocated bucket for queues of size 1.
Definition: framequeue.h:91
FFFrameBucket::frame
AVFrame * frame
Definition: framequeue.h:35
ff_framequeue_add
int ff_framequeue_add(FFFrameQueue *fq, AVFrame *frame)
Add a frame.
Definition: framequeue.c:67
AVFrame
This structure describes decoded (raw) audio or video data.
Definition: frame.h:421
FFFrameQueue::queue
FFFrameBucket * queue
Array of allocated buckets, used as a circular buffer.
Definition: framequeue.h:70
FFFrameQueue::allocated
size_t allocated
Size of the array of buckets.
Definition: framequeue.h:75
FFFrameBucket
FFFrameQueue: simple AVFrame queue API.
Definition: framequeue.h:34
FFFrameQueueGlobal::max_queued
size_t max_queued
Maximum number of allowed frames in the queues combined.
Definition: framequeue.h:49
FFFrameQueue::total_samples_tail
uint64_t total_samples_tail
Total number of samples dequeued from the queue.
Definition: framequeue.h:113
FFFrameQueueGlobal::queued
size_t queued
Total number of queued frames in the queues combined.
Definition: framequeue.h:54
FFFrameQueue::queued
size_t queued
Number of currently queued frames.
Definition: framequeue.h:86
FFFrameQueue::samples_skipped
int samples_skipped
Indicate that samples are skipped.
Definition: framequeue.h:118
FFFrameQueueGlobal
Structure to hold global options and statistics for frame queues.
Definition: framequeue.h:44
ff_framequeue_global_init
void ff_framequeue_global_init(FFFrameQueueGlobal *fqg)
Init a global structure.
Definition: framequeue.c:31
ff_framequeue_peek
AVFrame * ff_framequeue_peek(FFFrameQueue *fq, size_t idx)
Access a frame in the queue, without removing it.
Definition: framequeue.c:122
ff_framequeue_skip_samples
void ff_framequeue_skip_samples(FFFrameQueue *fq, size_t samples, AVRational time_base)
Skip samples from the first frame in the queue.
Definition: framequeue.c:133
AVRational
Rational number (pair of numerator and denominator).
Definition: rational.h:58
FFFrameQueue::total_frames_head
uint64_t total_frames_head
Total number of frames entered in the queue.
Definition: framequeue.h:96
FFFrameQueue
Queue of AVFrame pointers.
Definition: framequeue.h:60
FFFrameQueue::tail
size_t tail
Tail of the queue.
Definition: framequeue.h:81
frame.h
FFFrameQueue::total_samples_head
uint64_t total_samples_head
Total number of samples entered in the queue.
Definition: framequeue.h:107
FFFrameQueue::global
FFFrameQueueGlobal * global
Pointer to the global frame queue struct holding statistics and limits.
Definition: framequeue.h:65
ff_framequeue_queued_samples
static uint64_t ff_framequeue_queued_samples(const FFFrameQueue *fq)
Get the number of queued samples.
Definition: framequeue.h:166
ff_framequeue_init
void ff_framequeue_init(FFFrameQueue *fq, FFFrameQueueGlobal *fqg)
Init a frame queue and attach it to a global structure.
Definition: framequeue.c:50
frame
these buffered frames must be flushed immediately if a new input produces new the filter must not call request_frame to get more It must just process the frame or queue it The task of requesting more frames is left to the filter s request_frame method or the application If a filter has several the filter must be ready for frames arriving randomly on any input any filter with several inputs will most likely require some kind of queuing mechanism It is perfectly acceptable to have a limited queue and to drop frames when the inputs are too unbalanced request_frame For filters that do not use the this method is called when a frame is wanted on an output For a it should directly call filter_frame on the corresponding output For a if there are queued frames already one of these frames should be pushed If the filter should request a frame on one of its repeatedly until at least one frame has been pushed Return or at least make progress towards producing a frame
Definition: filter_design.txt:265
FFFrameQueue::total_frames_tail
uint64_t total_frames_tail
Total number of frames dequeued from the queue.
Definition: framequeue.h:102
ff_framequeue_queued_frames
static size_t ff_framequeue_queued_frames(const FFFrameQueue *fq)
Get the number of queued frames.
Definition: framequeue.h:158
ff_framequeue_take
AVFrame * ff_framequeue_take(FFFrameQueue *fq)
Take the first frame in the queue.
Definition: framequeue.c:104
samples
Filter the word “frame” indicates either a video frame or a group of audio samples
Definition: filter_design.txt:8
ff_framequeue_free
void ff_framequeue_free(FFFrameQueue *fq)
Free the queue and all queued frames.
Definition: framequeue.c:57
ff_framequeue_update_peeked
static void ff_framequeue_update_peeked(FFFrameQueue *fq, size_t idx)
Update the statistics after a frame accessed using ff_framequeue_peek() was modified.
Definition: framequeue.h:176