FFmpeg
sync_queue.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 #ifndef FFTOOLS_SYNC_QUEUE_H
20 #define FFTOOLS_SYNC_QUEUE_H
21 
22 #include <stdint.h>
23 
24 #include "libavcodec/packet.h"
25 
26 #include "libavutil/frame.h"
27 
31 };
32 
33 typedef union SyncQueueFrame {
37 
38 #define SQFRAME(frame) ((SyncQueueFrame){ .f = (frame) })
39 #define SQPKT(pkt) ((SyncQueueFrame){ .p = (pkt) })
40 
41 /**
42  * A sync queue provides timestamp synchronization between multiple streams.
43  * Some of these streams are marked as "limiting", then the queue ensures no
44  * stream gets ahead of any of the limiting streams.
45  */
46 typedef struct SyncQueue SyncQueue;
47 
48 /**
49  * Allocate a sync queue of the given type.
50  *
51  * @param buf_size_us maximum duration that will be buffered in microseconds
52  */
54 void sq_free(SyncQueue **sq);
55 
56 /**
57  * Add a new stream to the sync queue.
58  *
59  * @param limiting whether the stream is limiting, i.e. no other stream can be
60  * longer than this one
61  * @return
62  * - a non-negative stream index on success
63  * - a negative error code on error
64  */
65 int sq_add_stream(SyncQueue *sq, int limiting);
66 
67 /**
68  * Limit the number of output frames for stream with index stream_idx
69  * to max_frames.
70  */
71 void sq_limit_frames(SyncQueue *sq, unsigned int stream_idx,
72  uint64_t max_frames);
73 
74 /**
75  * Set a constant output audio frame size, in samples. Can only be used with
76  * SYNC_QUEUE_FRAMES queues and audio streams.
77  *
78  * All output frames will have exactly frame_samples audio samples, except
79  * possibly for the last one, which may have fewer.
80  */
81 void sq_frame_samples(SyncQueue *sq, unsigned int stream_idx,
82  int frame_samples);
83 
84 /**
85  * Submit a frame for the stream with index stream_idx.
86  *
87  * On success, the sync queue takes ownership of the frame and will reset the
88  * contents of the supplied frame. On failure, the frame remains owned by the
89  * caller.
90  *
91  * Sending a frame with NULL contents marks the stream as finished.
92  *
93  * @return
94  * - 0 on success
95  * - AVERROR_EOF when no more frames should be submitted for this stream
96  * - another a negative error code on failure
97  */
98 int sq_send(SyncQueue *sq, unsigned int stream_idx, SyncQueueFrame frame);
99 
100 /**
101  * Read a frame from the queue.
102  *
103  * @param stream_idx index of the stream to read a frame for. May be -1, then
104  * try to read a frame from any stream that is ready for
105  * output.
106  * @param frame output frame will be written here on success. The frame is owned
107  * by the caller.
108  *
109  * @return
110  * - a non-negative index of the stream to which the returned frame belongs
111  * - AVERROR(EAGAIN) when more frames need to be submitted to the queue
112  * - AVERROR_EOF when no more frames will be available for this stream (for any
113  * stream if stream_idx is -1)
114  * - another negative error code on failure
115  */
116 int sq_receive(SyncQueue *sq, int stream_idx, SyncQueueFrame frame);
117 
118 #endif // FFTOOLS_SYNC_QUEUE_H
frame_samples
static int frame_samples(const SyncQueue *sq, SyncQueueFrame frame)
Definition: sync_queue.c:141
SYNC_QUEUE_PACKETS
@ SYNC_QUEUE_PACKETS
Definition: sync_queue.h:29
SyncQueueFrame::f
AVFrame * f
Definition: sync_queue.h:34
SyncQueueType
SyncQueueType
Definition: sync_queue.h:28
int64_t
long long int64_t
Definition: coverity.c:34
AVFrame
This structure describes decoded (raw) audio or video data.
Definition: frame.h:374
SyncQueueFrame::p
AVPacket * p
Definition: sync_queue.h:35
sq_add_stream
int sq_add_stream(SyncQueue *sq, int limiting)
Add a new stream to the sync queue.
Definition: sync_queue.c:620
type
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 type
Definition: writing_filters.txt:86
SyncQueueFrame
Definition: sync_queue.h:33
sq_limit_frames
void sq_limit_frames(SyncQueue *sq, unsigned int stream_idx, uint64_t max_frames)
Limit the number of output frames for stream with index stream_idx to max_frames.
Definition: sync_queue.c:649
frame.h
SyncQueue::logctx
void * logctx
Definition: sync_queue.c:91
sq_receive
int sq_receive(SyncQueue *sq, int stream_idx, SyncQueueFrame frame)
Read a frame from the queue.
Definition: sync_queue.c:608
packet.h
SyncQueue::buf_size_us
int64_t buf_size_us
Definition: sync_queue.c:102
sq_alloc
SyncQueue * sq_alloc(enum SyncQueueType type, int64_t buf_size_us, void *logctx)
Allocate a sync queue of the given type.
Definition: sync_queue.c:675
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
SyncQueue
A sync queue provides timestamp synchronization between multiple streams.
Definition: sync_queue.c:88
AVPacket
This structure stores compressed data.
Definition: packet.h:510
sq_free
void sq_free(SyncQueue **sq)
Definition: sync_queue.c:699
SYNC_QUEUE_FRAMES
@ SYNC_QUEUE_FRAMES
Definition: sync_queue.h:30
sq_frame_samples
void sq_frame_samples(SyncQueue *sq, unsigned int stream_idx, int frame_samples)
Set a constant output audio frame size, in samples.
Definition: sync_queue.c:661
sq_send
int sq_send(SyncQueue *sq, unsigned int stream_idx, SyncQueueFrame frame)
Submit a frame for the stream with index stream_idx.
Definition: sync_queue.c:343