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  * It is currently empty.
45  */
46 typedef struct FFFrameQueueGlobal {
47  char dummy; /* C does not allow empty structs */
49 
50 /**
51  * Queue of AVFrame pointers.
52  */
53 typedef struct FFFrameQueue {
54 
55  /**
56  * Array of allocated buckets, used as a circular buffer.
57  */
59 
60  /**
61  * Size of the array of buckets.
62  */
63  size_t allocated;
64 
65  /**
66  * Tail of the queue.
67  * It is the index in the array of the next frame to take.
68  */
69  size_t tail;
70 
71  /**
72  * Number of currently queued frames.
73  */
74  size_t queued;
75 
76  /**
77  * Pre-allocated bucket for queues of size 1.
78  */
80 
81  /**
82  * Total number of frames entered in the queue.
83  */
85 
86  /**
87  * Total number of frames dequeued from the queue.
88  * queued = total_frames_head - total_frames_tail
89  */
91 
92  /**
93  * Total number of samples entered in the queue.
94  */
96 
97  /**
98  * Total number of samples dequeued from the queue.
99  * queued_samples = total_samples_head - total_samples_tail
100  */
102 
103  /**
104  * Indicate that samples are skipped
105  */
107 
108 } FFFrameQueue;
109 
110 /**
111  * Init a global structure.
112  */
114 
115 /**
116  * Init a frame queue and attach it to a global structure.
117  */
119 
120 /**
121  * Free the queue and all queued frames.
122  */
124 
125 /**
126  * Add a frame.
127  * @return >=0 or an AVERROR code.
128  */
130 
131 /**
132  * Take the first frame in the queue.
133  * Must not be used with empty queues.
134  */
136 
137 /**
138  * Access a frame in the queue, without removing it.
139  * The first frame is numbered 0; the designated frame must exist.
140  */
141 AVFrame *ff_framequeue_peek(FFFrameQueue *fq, size_t idx);
142 
143 /**
144  * Get the number of queued frames.
145  */
146 static inline size_t ff_framequeue_queued_frames(const FFFrameQueue *fq)
147 {
148  return fq->queued;
149 }
150 
151 /**
152  * Get the number of queued samples.
153  */
154 static inline uint64_t ff_framequeue_queued_samples(const FFFrameQueue *fq)
155 {
156  return fq->total_samples_head - fq->total_samples_tail;
157 }
158 
159 /**
160  * Update the statistics after a frame accessed using ff_framequeue_peek()
161  * was modified.
162  * Currently used only as a marker.
163  */
164 static inline void ff_framequeue_update_peeked(FFFrameQueue *fq, size_t idx)
165 {
166 }
167 
168 /**
169  * Skip samples from the first frame in the queue.
170  *
171  * This function must be used when the first frame was accessed using
172  * ff_framequeue_peek() and samples were consumed from it.
173  * It adapts the data pointers and timestamps of the head frame to account
174  * for the skipped samples.
175  */
176 void ff_framequeue_skip_samples(FFFrameQueue *fq, size_t samples, AVRational time_base);
177 
178 #endif /* AVFILTER_FRAMEQUEUE_H */
FFFrameQueue::first_bucket
FFFrameBucket first_bucket
Pre-allocated bucket for queues of size 1.
Definition: framequeue.h:79
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:63
AVFrame
This structure describes decoded (raw) audio or video data.
Definition: frame.h:325
FFFrameQueue::queue
FFFrameBucket * queue
Array of allocated buckets, used as a circular buffer.
Definition: framequeue.h:58
FFFrameQueue::allocated
size_t allocated
Size of the array of buckets.
Definition: framequeue.h:63
FFFrameBucket
FFFrameQueue: simple AVFrame queue API.
Definition: framequeue.h:34
FFFrameQueueGlobal::dummy
char dummy
Definition: framequeue.h:47
FFFrameQueue::total_samples_tail
uint64_t total_samples_tail
Total number of samples dequeued from the queue.
Definition: framequeue.h:101
FFFrameQueue::queued
size_t queued
Number of currently queued frames.
Definition: framequeue.h:74
FFFrameQueue::samples_skipped
int samples_skipped
Indicate that samples are skipped.
Definition: framequeue.h:106
FFFrameQueueGlobal
Structure to hold global options and statistics for frame queues.
Definition: framequeue.h:46
ff_framequeue_global_init
void ff_framequeue_global_init(FFFrameQueueGlobal *fqg)
Init a global structure.
Definition: framequeue.c:30
ff_framequeue_peek
AVFrame * ff_framequeue_peek(FFFrameQueue *fq, size_t idx)
Access a frame in the queue, without removing it.
Definition: framequeue.c:115
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:126
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:84
FFFrameQueue
Queue of AVFrame pointers.
Definition: framequeue.h:53
FFFrameQueue::tail
size_t tail
Tail of the queue.
Definition: framequeue.h:69
frame.h
FFFrameQueue::total_samples_head
uint64_t total_samples_head
Total number of samples entered in the queue.
Definition: framequeue.h:95
ff_framequeue_queued_samples
static uint64_t ff_framequeue_queued_samples(const FFFrameQueue *fq)
Get the number of queued samples.
Definition: framequeue.h:154
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:47
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:264
FFFrameQueue::total_frames_tail
uint64_t total_frames_tail
Total number of frames dequeued from the queue.
Definition: framequeue.h:90
ff_framequeue_queued_frames
static size_t ff_framequeue_queued_frames(const FFFrameQueue *fq)
Get the number of queued frames.
Definition: framequeue.h:146
ff_framequeue_take
AVFrame * ff_framequeue_take(FFFrameQueue *fq)
Take the first frame in the queue.
Definition: framequeue.c:98
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:53
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:164