FFmpeg
Loading...
Searching...
No Matches
graph.h
Go to the documentation of this file.
1/*
2 * Copyright (C) 2024 Niklas Haas
3 *
4 * This file is part of FFmpeg.
5 *
6 * FFmpeg is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * FFmpeg is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with FFmpeg; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19 */
20
21#ifndef SWSCALE_GRAPH_H
22#define SWSCALE_GRAPH_H
23
24#include <stdbool.h>
25
27#include "libavutil/buffer.h"
28
29#include "swscale.h"
30#include "format.h"
31#include "lut3d.h"
32
34{
36 return (plane == 1 || plane == 2) ? desc->log2_chroma_h : 0;
37}
38
39typedef struct SwsPass SwsPass;
40typedef struct SwsGraph SwsGraph;
41
42/**
43 * Output `h` lines of filtered data. `out` and `in` point to the
44 * start of the image buffer for this pass.
45 */
46typedef void (*SwsPassFunc)(const SwsFrame *out, const SwsFrame *in,
47 int y, int h, const SwsPass *pass);
48
49/**
50 * Function to run from the main thread before processing any lines.
51 */
52typedef int (*SwsPassSetup)(const SwsFrame *out, const SwsFrame *in,
53 const SwsPass *pass);
54
55/**
56 * Represents an output buffer for a filter pass. During filter graph
57 * construction, these merely hold the metadata. Allocation of the underlying
58 * storage is deferred until after all filter passes are settled.
59 */
60typedef struct SwsPassBuffer {
62
63 int width, height; /* dimensions of this buffer */
64 AVFrame *avframe; /* backing storage for `frame` */
65
66 /* Optional allocation hints for optimal performance */
67 int width_align; /* Align width to multiple of this */
68 int width_pad; /* Extra padding pixels */
69
70 /**
71 * Map of planes which are directly copied from the pass input. These
72 * may be promoted from a memcpy to a refcopy.
73 *
74 * Each entry maps the output index to the corresponding input plane
75 * index, or -1 for no copythrough.
76 */
77 int plane_copy[4];
79
80/**
81 * Represents a single filter pass in the scaling graph. Each filter will
82 * read from some previous pass's output, and write to a buffer associated
83 * with the pass (or into the final output image).
84 */
85struct SwsPass {
87
88 /**
89 * Filter main execution function. Called from multiple threads, with
90 * the granularity dictated by `slice_h`. Individual slices sent to `run`
91 * are always equal to (or smaller than, for the last slice) `slice_h`.
92 */
94 SwsBackend backend; /* backend this pass is using, or 0 */
95 int cpu_flags; /* CPU flags used by the backend (informative) */
96 enum AVPixelFormat format; /* new pixel format */
97 int lines; /* pass dispatch size */
98 int slice_h; /* filter granularity */
100
101 /**
102 * Filter input. This pass's output will be resolved to form this pass's.
103 * input. If NULL, the original input image is used.
104 */
106
107 /**
108 * Filter output buffer. This struct is always allocated.
109 */
110 SwsPassBuffer *output; /* refstruct */
111
112 /**
113 * Called once from the main thread before running the filter. Optional.
114 * Returns 0 or a negative error code.
115 */
117
118 /**
119 * Optional private state and associated free() function.
120 */
121 void (*free)(void *priv);
122 void *priv;
123};
124
125/**
126 * Align `width` to the optimal size for `pass`.
127 */
128int ff_sws_pass_aligned_width(const SwsPass *pass, int width);
129
130/**
131 * Filter graph, which represents a 'baked' pixel format conversion.
132 */
133typedef struct SwsGraph {
136 int num_threads; /* resolved at init() time */
137 bool incomplete; /* set during init() if formats had to be inferred */
138 bool noop; /* set during init() if the graph is a no-op */
139 SwsBackend backend; /* backends this graph is using, set during init() */
140
142
143 /**
144 * Map of planes which directly copied from the input. These may be
145 * promoted from a memcpy to a refcopy. This requires special handling
146 * by the caller.
147 *
148 * Each entry maps the output index to the corresponding input plane
149 * index, or -1 for no copythrough.
150 */
152
153 /** Sorted sequence of filter passes to apply */
156
157 /**
158 * Cached copy of the public options that were used to construct this
159 * SwsGraph. Used only to detect when the graph needs to be reinitialized.
160 */
162
163 /**
164 * Currently active format and processing parameters.
165 */
167
168 /**
169 * 3DLUT state used for gamut/tone mapping. (Optional)
170 */
171 SwsLut3D *lut3d; /* refstruct */
172
173 /**
174 * Temporary execution state inside ff_sws_graph_run(); used to pass
175 * data to worker threads.
176 */
177 struct {
178 const SwsPass *pass; /* current filter pass */
179 const SwsFrame *input; /* current filter pass input/output */
182} SwsGraph;
183
184/**
185 * Allocate an empty SwsGraph. Returns NULL on failure.
186 */
188
189/**
190 * Initialize the filter graph for a given pair of formats. Returns 0 or a
191 * negative error.
192 */
194 const SwsFormat *src);
195
196
197/**
198 * Allocate and add a new pass to the filter graph. Takes over ownership of
199 * `priv`, even on failure.
200 *
201 * @param graph Filter graph to add the pass to.
202 * @param fmt Pixel format of the output image.
203 * @param w Width of the output image.
204 * @param h Height of the output image.
205 * @param input Previous pass to read from, or NULL for the input image.
206 * @param lines Override the number of lines processed for this pass. (Optional)
207 * @param align Minimum slice alignment for this pass, or 0 for no threading.
208 * @param run Filter function to run.
209 * @param setup Optional setup function to run from the main thread.
210 * @param priv Private state for the filter run function.
211 * @param free Function to free the private state.
212 * @param out_pass The newly added pass will be written here on success.
213 * @return 0 or a negative error code
214 */
215int ff_sws_graph_add_pass(SwsGraph *graph, enum AVPixelFormat fmt,
216 int width, int height, SwsPass *input,
217 int lines, int align,
219 void *priv, void (*free)(void *priv),
220 SwsPass **out_pass);
221
222/**
223 * Link the output buffers to a different pass, rather than allocating
224 * new image buffers. This allows reusing the same buffer for multiple passes,
225 * e.g. in the case of in-place passes or partial passes that modify different
226 * planes.
227 *
228 * Any existing buffer on `dst` will be ignored/unref'd.
229 **/
231
232/**
233 * Remove all passes added since the given index.
234 */
235void ff_sws_graph_rollback(SwsGraph *graph, int since_idx);
236
237/**
238 * Uninitialize any state associate with this filter graph and free it.
239 */
240void ff_sws_graph_free(SwsGraph **graph);
241
242/**
243 * Update dynamic per-frame HDR metadata without requiring a full reinit.
244 */
246
247/**
248 * Wrapper around ff_sws_graph_init() that reuses the existing graph if the
249 * format is compatible. This will also update dynamic per-frame metadata.
250 *
251 * Must also be called after changing any of the fields in `ctx`, or else they
252 * will have no effect.
253 */
255 const SwsFormat *src);
256
257/**
258 * Dispatch the filter graph on a single field of the given frames. Internally
259 * threaded.
260 */
261int ff_sws_graph_run(SwsGraph *graph, const AVFrame *dst, const AVFrame *src);
262
263#endif /* SWSCALE_GRAPH_H */
uint8_t ptrdiff_t const uint8_t ptrdiff_t int intptr_t intptr_t int int16_t * dst
Definition dsp.h:97
static FILE * out
static AVFormatContext * ctx
static const uint8_t *BS_FUNC align(BSCTX *bc)
Skip bits to a byte boundary.
refcounted data buffer API
void ff_sws_graph_update_metadata(SwsGraph *graph, const SwsColor *color)
Update dynamic per-frame HDR metadata without requiring a full reinit.
Definition graph.c:1002
int ff_sws_graph_init(SwsGraph *graph, SwsContext *ctx, const SwsFormat *dst, const SwsFormat *src)
Initialize the filter graph for a given pair of formats.
Definition graph.c:899
void(* SwsPassFunc)(const SwsFrame *out, const SwsFrame *in, int y, int h, const SwsPass *pass)
Output h lines of filtered data.
Definition graph.h:46
void ff_sws_pass_link_output(SwsPass *dst, const SwsPass *src)
Link the output buffers to a different pass, rather than allocating new image buffers.
Definition graph.c:256
int(* SwsPassSetup)(const SwsFrame *out, const SwsFrame *in, const SwsPass *pass)
Function to run from the main thread before processing any lines.
Definition graph.h:52
void ff_sws_graph_rollback(SwsGraph *graph, int since_idx)
Remove all passes added since the given index.
Definition graph.c:950
int ff_sws_graph_add_pass(SwsGraph *graph, enum AVPixelFormat fmt, int width, int height, SwsPass *input, int lines, int align, SwsPassFunc run, SwsPassSetup setup, void *priv, void(*free)(void *priv), SwsPass **out_pass)
Allocate and add a new pass to the filter graph.
Definition graph.c:198
int ff_sws_graph_run(SwsGraph *graph, const AVFrame *dst, const AVFrame *src)
Dispatch the filter graph on a single field of the given frames.
Definition graph.c:1041
SwsGraph * ff_sws_graph_alloc(void)
Allocate an empty SwsGraph.
Definition graph.c:881
int ff_sws_pass_aligned_width(const SwsPass *pass, int width)
Align width to the optimal size for pass.
Definition graph.c:46
int ff_sws_graph_reinit(SwsGraph *graph, SwsContext *ctx, const SwsFormat *dst, const SwsFormat *src)
Wrapper around ff_sws_graph_init() that reuses the existing graph if the format is compatible.
Definition graph.c:988
static av_always_inline av_const int ff_fmt_vshift(enum AVPixelFormat fmt, int plane)
Definition graph.h:33
void ff_sws_graph_free(SwsGraph **graph)
Uninitialize any state associate with this filter graph and free it.
Definition graph.c:957
SwsBackend
Definition swscale.h:110
#define av_always_inline
Definition attributes.h:72
#define av_const
Definition attributes.h:111
const char * desc
Definition libsvtav1.c:83
const AVPixFmtDescriptor * av_pix_fmt_desc_get(enum AVPixelFormat pix_fmt)
Definition pixdesc.c:3484
AVPixelFormat
Pixel format.
Definition pixfmt.h:71
struct AVSliceThread AVSliceThread
Definition slicethread.h:25
A reference to a data buffer.
Definition buffer.h:82
This structure describes decoded (raw) audio or video data.
Definition frame.h:479
Descriptor that unambiguously describes how the bits of a pixel are stored in the up to 4 data planes...
Definition pixdesc.h:69
Main external API structure.
Definition swscale.h:227
Represents a view into a single field of frame data.
Definition format.h:206
Filter graph, which represents a 'baked' pixel format conversion.
Definition graph.h:133
bool noop
Definition graph.h:138
const SwsFrame * output
Definition graph.h:180
SwsPass ** passes
Sorted sequence of filter passes to apply.
Definition graph.h:154
bool incomplete
Definition graph.h:137
SwsFormat src
Currently active format and processing parameters.
Definition graph.h:166
int num_passes
Definition graph.h:155
const SwsPass * pass
Definition graph.h:178
SwsContext opts_copy
Cached copy of the public options that were used to construct this SwsGraph.
Definition graph.h:161
SwsLut3D * lut3d
3DLUT state used for gamut/tone mapping.
Definition graph.h:171
SwsFormat dst
Definition graph.h:166
SwsContext * ctx
Definition graph.h:134
AVBufferRef * hw_frames_ref
Definition graph.h:141
int plane_copy[4]
Map of planes which directly copied from the input.
Definition graph.h:151
int num_threads
Definition graph.h:136
AVSliceThread * slicethread
Definition graph.h:135
SwsBackend backend
Definition graph.h:139
struct SwsGraph::@252226332054334034101247363262236031041275151254 exec
Temporary execution state inside ff_sws_graph_run(); used to pass data to worker threads.
const SwsFrame * input
Definition graph.h:179
Represents an output buffer for a filter pass.
Definition graph.h:60
int width
Definition graph.h:63
int height
Definition graph.h:63
int width_pad
Definition graph.h:68
SwsFrame frame
Definition graph.h:61
AVFrame * avframe
Definition graph.h:64
int width_align
Definition graph.h:67
int plane_copy[4]
Map of planes which are directly copied from the pass input.
Definition graph.h:77
Represents a single filter pass in the scaling graph.
Definition graph.h:85
int cpu_flags
Definition graph.h:95
int num_slices
Definition graph.h:99
SwsPass * input
Filter input.
Definition graph.h:105
void * priv
Definition graph.h:122
enum AVPixelFormat format
Definition graph.h:96
int lines
Definition graph.h:97
const SwsGraph * graph
Definition graph.h:86
SwsPassFunc run
Filter main execution function.
Definition graph.h:93
SwsPassBuffer * output
Filter output buffer.
Definition graph.h:110
void(* free)(void *priv)
Optional private state and associated free() function.
Definition graph.h:121
SwsBackend backend
Definition graph.h:94
SwsPassSetup setup
Called once from the main thread before running the filter.
Definition graph.h:116
int slice_h
Definition graph.h:98
uint8_t run
Definition svq3.c:207
external API header
#define src
Definition vp8dsp.c:248
#define height
Definition dsp.h:99
#define width
Definition dsp.h:99