/src/ffmpeg/libswscale/graph.h

Source
/*
 * Copyright (C) 2024 Niklas Haas
 *
 * This file is part of FFmpeg.
 *
 * FFmpeg is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * FFmpeg is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with FFmpeg; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */

#ifndef SWSCALE_GRAPH_H
#define SWSCALE_GRAPH_H

#include <stdbool.h>

#include "libavutil/slicethread.h"
#include "libavutil/buffer.h"

#include "swscale.h"
#include "format.h"
#include "lut3d.h"

static av_always_inline av_const int ff_fmt_vshift(enum AVPixelFormat fmt, int plane)
{
    const AVPixFmtDescriptor *desc = av_pix_fmt_desc_get(fmt);
    return (plane == 1 || plane == 2) ? desc->log2_chroma_h : 0;
}

typedef struct SwsPass  SwsPass;
typedef struct SwsGraph SwsGraph;

/**
 * Output `h` lines of filtered data. `out` and `in` point to the
 * start of the image buffer for this pass.
 */
typedef void (*SwsPassFunc)(const SwsFrame *out, const SwsFrame *in,
                            int y, int h, const SwsPass *pass);

/**
 * Function to run from the main thread before processing any lines.
 */
typedef int (*SwsPassSetup)(const SwsFrame *out, const SwsFrame *in,
                            const SwsPass *pass);

/**
 * Represents an output buffer for a filter pass. During filter graph
 * construction, these merely hold the metadata. Allocation of the underlying
 * storage is deferred until after all filter passes are settled.
 */
typedef struct SwsPassBuffer {
    SwsFrame frame;

    int width, height; /* dimensions of this buffer */
    AVFrame *avframe;  /* backing storage for `frame` */

    /* Optional allocation hints for optimal performance */
    int width_align;   /* Align width to multiple of this */
    int width_pad;     /* Extra padding pixels */

    /**
     * Map of planes which are directly copied from the pass input. These
     * may be promoted from a memcpy to a refcopy.
     *
     * Each entry maps the output index to the corresponding input plane
     * index, or -1 for no copythrough.
     */
    int plane_copy[4];
} SwsPassBuffer;

/**
 * Represents a single filter pass in the scaling graph. Each filter will
 * read from some previous pass's output, and write to a buffer associated
 * with the pass (or into the final output image).
 */
struct SwsPass {
    const SwsGraph *graph;

    /**
     * Filter main execution function. Called from multiple threads, with
     * the granularity dictated by `slice_h`. Individual slices sent to `run`
     * are always equal to (or smaller than, for the last slice) `slice_h`.
     */
    SwsPassFunc run;
    SwsBackend backend; /* backend this pass is using, or 0 */
    enum AVPixelFormat format; /* new pixel format */
    int lines;         /* pass dispatch size */
    int slice_h;       /* filter granularity */
    int num_slices;

    /**
     * Filter input. This pass's output will be resolved to form this pass's.
     * input. If NULL, the original input image is used.
     */
    SwsPass *input;

    /**
     * Filter output buffer. This struct is always allocated.
     */
    SwsPassBuffer *output; /* refstruct */

    /**
     * Called once from the main thread before running the filter. Optional.
     * Returns 0 or a negative error code.
     */
    SwsPassSetup setup;

    /**
     * Optional private state and associated free() function.
     */
    void (*free)(void *priv);
    void *priv;
};

/**
 * Align `width` to the optimal size for `pass`.
 */
int ff_sws_pass_aligned_width(const SwsPass *pass, int width);

/**
 * Filter graph, which represents a 'baked' pixel format conversion.
 */
typedef struct SwsGraph {
    SwsContext *ctx;
    AVSliceThread *slicethread;
    int num_threads; /* resolved at init() time */
    bool incomplete; /* set during init() if formats had to be inferred */
    bool noop;       /* set during init() if the graph is a no-op */
    SwsBackend backend; /* backends this graph is using, set during init() */

    AVBufferRef *hw_frames_ref;

    /**
     * Map of planes which directly copied from the input. These may be
     * promoted from a memcpy to a refcopy. This requires special handling
     * by the caller.
     *
     * Each entry maps the output index to the corresponding input plane
     * index, or -1 for no copythrough.
     */
    int plane_copy[4];

    /** Sorted sequence of filter passes to apply */
    SwsPass **passes;
    int num_passes;

    /**
     * Cached copy of the public options that were used to construct this
     * SwsGraph. Used only to detect when the graph needs to be reinitialized.
     */
    SwsContext opts_copy;

    /**
     * Currently active format and processing parameters.
     */
    SwsFormat src, dst;

    /**
     * 3DLUT state used for gamut/tone mapping. (Optional)
     */
    SwsLut3D *lut3d; /* refstruct */

    /**
     * Temporary execution state inside ff_sws_graph_run(); used to pass
     * data to worker threads.
     */
    struct {
        const SwsPass *pass; /* current filter pass */
        const SwsFrame *input; /* current filter pass input/output */
        const SwsFrame *output;
    } exec;
} SwsGraph;

/**
 * Allocate an empty SwsGraph. Returns NULL on failure.
 */
SwsGraph *ff_sws_graph_alloc(void);

/**
 * Initialize the filter graph for a given pair of formats. Returns 0 or a
 * negative error.
 */
int ff_sws_graph_init(SwsGraph *graph, SwsContext *ctx, const SwsFormat *dst,
                      const SwsFormat *src);


/**
 * Allocate and add a new pass to the filter graph. Takes over ownership of
 * `priv`, even on failure.
 *
 * @param graph  Filter graph to add the pass to.
 * @param fmt    Pixel format of the output image.
 * @param w      Width of the output image.
 * @param h      Height of the output image.
 * @param input  Previous pass to read from, or NULL for the input image.
 * @param lines  Override the number of lines processed for this pass. (Optional)
 * @param align  Minimum slice alignment for this pass, or 0 for no threading.
 * @param run    Filter function to run.
 * @param setup  Optional setup function to run from the main thread.
 * @param priv   Private state for the filter run function.
 * @param free   Function to free the private state.
 * @param out_pass The newly added pass will be written here on success.
 * @return 0 or a negative error code
 */
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);

/**
 * Link the output buffers to a different pass, rather than allocating
 * new image buffers. This allows reusing the same buffer for multiple passes,
 * e.g. in the case of in-place passes or partial passes that modify different
 * planes.
 *
 * Any existing buffer on `dst` will be ignored/unref'd.
 **/
void ff_sws_pass_link_output(SwsPass *dst, const SwsPass *src);

/**
 * Remove all passes added since the given index.
 */
void ff_sws_graph_rollback(SwsGraph *graph, int since_idx);

/**
 * Uninitialize any state associate with this filter graph and free it.
 */
void ff_sws_graph_free(SwsGraph **graph);

/**
 * Update dynamic per-frame HDR metadata without requiring a full reinit.
 */
void ff_sws_graph_update_metadata(SwsGraph *graph, const SwsColor *color);

/**
 * Wrapper around ff_sws_graph_init() that reuses the existing graph if the
 * format is compatible. This will also update dynamic per-frame metadata.
 *
 * Must also be called after changing any of the fields in `ctx`, or else they
 * will have no effect.
 */
int ff_sws_graph_reinit(SwsGraph *graph, SwsContext *ctx, const SwsFormat *dst,
                        const SwsFormat *src);

/**
 * Dispatch the filter graph on a single field of the given frames. Internally
 * threaded.
 */
int ff_sws_graph_run(SwsGraph *graph, const AVFrame *dst, const AVFrame *src);

#endif /* SWSCALE_GRAPH_H */

Coverage Report

Created: 2026-08-17 07:50

Line	Count	Source
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
26		#include "libavutil/slicethread.h"
27		#include "libavutil/buffer.h"
28
29		#include "swscale.h"
30		#include "format.h"
31		#include "lut3d.h"
32
33		static av_always_inline av_const int ff_fmt_vshift(enum AVPixelFormat fmt, int plane)
34	0	{
35	0	const AVPixFmtDescriptor *desc = av_pix_fmt_desc_get(fmt);
36	0	return (plane == 1 \|\| plane == 2) ? desc->log2_chroma_h : 0;
37	0	} Unexecuted instantiation: swscale.c:ff_fmt_vshift Unexecuted instantiation: utils.c:ff_fmt_vshift Unexecuted instantiation: vscale.c:ff_fmt_vshift Unexecuted instantiation: yuv2rgb.c:ff_fmt_vshift Unexecuted instantiation: alphablend.c:ff_fmt_vshift Unexecuted instantiation: format.c:ff_fmt_vshift Unexecuted instantiation: graph.c:ff_fmt_vshift Unexecuted instantiation: hscale_fast_bilinear.c:ff_fmt_vshift Unexecuted instantiation: input.c:ff_fmt_vshift Unexecuted instantiation: ops.c:ff_fmt_vshift Unexecuted instantiation: ops_dispatch.c:ff_fmt_vshift Unexecuted instantiation: ops_memcpy.c:ff_fmt_vshift Unexecuted instantiation: ops_optimizer.c:ff_fmt_vshift Unexecuted instantiation: options.c:ff_fmt_vshift Unexecuted instantiation: output.c:ff_fmt_vshift Unexecuted instantiation: rgb2rgb.c:ff_fmt_vshift Unexecuted instantiation: slice.c:ff_fmt_vshift Unexecuted instantiation: swscale_unscaled.c:ff_fmt_vshift Unexecuted instantiation: uops.c:ff_fmt_vshift Unexecuted instantiation: uops_backend.c:ff_fmt_vshift Unexecuted instantiation: gamma.c:ff_fmt_vshift Unexecuted instantiation: hscale.c:ff_fmt_vshift Unexecuted instantiation: ops_chain.c:ff_fmt_vshift
38
39		typedef struct SwsPass SwsPass;
40		typedef 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		*/
46		typedef 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		*/
52		typedef 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		*/
60		typedef struct SwsPassBuffer {
61		SwsFrame frame;
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];
78		} SwsPassBuffer;
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		*/
85		struct SwsPass {
86		const SwsGraph *graph;
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		*/
93		SwsPassFunc run;
94		SwsBackend backend; /* backend this pass is using, or 0 */
95		enum AVPixelFormat format; /* new pixel format */
96		int lines; /* pass dispatch size */
97		int slice_h; /* filter granularity */
98		int num_slices;
99
100		/**
101		* Filter input. This pass's output will be resolved to form this pass's.
102		* input. If NULL, the original input image is used.
103		*/
104		SwsPass *input;
105
106		/**
107		* Filter output buffer. This struct is always allocated.
108		*/
109		SwsPassBuffer output; / refstruct */
110
111		/**
112		* Called once from the main thread before running the filter. Optional.
113		* Returns 0 or a negative error code.
114		*/
115		SwsPassSetup setup;
116
117		/**
118		* Optional private state and associated free() function.
119		*/
120		void (free)(void priv);
121		void *priv;
122		};
123
124		/**
125		* Align `width` to the optimal size for `pass`.
126		*/
127		int ff_sws_pass_aligned_width(const SwsPass *pass, int width);
128
129		/**
130		* Filter graph, which represents a 'baked' pixel format conversion.
131		*/
132		typedef struct SwsGraph {
133		SwsContext *ctx;
134		AVSliceThread *slicethread;
135		int num_threads; /* resolved at init() time */
136		bool incomplete; /* set during init() if formats had to be inferred */
137		bool noop; /* set during init() if the graph is a no-op */
138		SwsBackend backend; /* backends this graph is using, set during init() */
139
140		AVBufferRef *hw_frames_ref;
141
142		/**
143		* Map of planes which directly copied from the input. These may be
144		* promoted from a memcpy to a refcopy. This requires special handling
145		* by the caller.
146		*
147		* Each entry maps the output index to the corresponding input plane
148		* index, or -1 for no copythrough.
149		*/
150		int plane_copy[4];
151
152		/** Sorted sequence of filter passes to apply */
153		SwsPass **passes;
154		int num_passes;
155
156		/**
157		* Cached copy of the public options that were used to construct this
158		* SwsGraph. Used only to detect when the graph needs to be reinitialized.
159		*/
160		SwsContext opts_copy;
161
162		/**
163		* Currently active format and processing parameters.
164		*/
165		SwsFormat src, dst;
166
167		/**
168		* 3DLUT state used for gamut/tone mapping. (Optional)
169		*/
170		SwsLut3D lut3d; / refstruct */
171
172		/**
173		* Temporary execution state inside ff_sws_graph_run(); used to pass
174		* data to worker threads.
175		*/
176		struct {
177		const SwsPass pass; / current filter pass */
178		const SwsFrame input; / current filter pass input/output */
179		const SwsFrame *output;
180		} exec;
181		} SwsGraph;
182
183		/**
184		* Allocate an empty SwsGraph. Returns NULL on failure.
185		*/
186		SwsGraph *ff_sws_graph_alloc(void);
187
188		/**
189		* Initialize the filter graph for a given pair of formats. Returns 0 or a
190		* negative error.
191		*/
192		int ff_sws_graph_init(SwsGraph graph, SwsContext ctx, const SwsFormat *dst,
193		const SwsFormat *src);
194
195
196		/**
197		* Allocate and add a new pass to the filter graph. Takes over ownership of
198		* `priv`, even on failure.
199		*
200		* @param graph Filter graph to add the pass to.
201		* @param fmt Pixel format of the output image.
202		* @param w Width of the output image.
203		* @param h Height of the output image.
204		* @param input Previous pass to read from, or NULL for the input image.
205		* @param lines Override the number of lines processed for this pass. (Optional)
206		* @param align Minimum slice alignment for this pass, or 0 for no threading.
207		* @param run Filter function to run.
208		* @param setup Optional setup function to run from the main thread.
209		* @param priv Private state for the filter run function.
210		* @param free Function to free the private state.
211		* @param out_pass The newly added pass will be written here on success.
212		* @return 0 or a negative error code
213		*/
214		int ff_sws_graph_add_pass(SwsGraph *graph, enum AVPixelFormat fmt,
215		int width, int height, SwsPass *input,
216		int lines, int align,
217		SwsPassFunc run, SwsPassSetup setup,
218		void priv, void (free)(void *priv),
219		SwsPass **out_pass);
220
221		/**
222		* Link the output buffers to a different pass, rather than allocating
223		* new image buffers. This allows reusing the same buffer for multiple passes,
224		* e.g. in the case of in-place passes or partial passes that modify different
225		* planes.
226		*
227		* Any existing buffer on `dst` will be ignored/unref'd.
228		**/
229		void ff_sws_pass_link_output(SwsPass dst, const SwsPass src);
230
231		/**
232		* Remove all passes added since the given index.
233		*/
234		void ff_sws_graph_rollback(SwsGraph *graph, int since_idx);
235
236		/**
237		* Uninitialize any state associate with this filter graph and free it.
238		*/
239		void ff_sws_graph_free(SwsGraph **graph);
240
241		/**
242		* Update dynamic per-frame HDR metadata without requiring a full reinit.
243		*/
244		void ff_sws_graph_update_metadata(SwsGraph graph, const SwsColor color);
245
246		/**
247		* Wrapper around ff_sws_graph_init() that reuses the existing graph if the
248		* format is compatible. This will also update dynamic per-frame metadata.
249		*
250		* Must also be called after changing any of the fields in `ctx`, or else they
251		* will have no effect.
252		*/
253		int ff_sws_graph_reinit(SwsGraph graph, SwsContext ctx, const SwsFormat *dst,
254		const SwsFormat *src);
255
256		/**
257		* Dispatch the filter graph on a single field of the given frames. Internally
258		* threaded.
259		*/
260		int ff_sws_graph_run(SwsGraph graph, const AVFrame dst, const AVFrame *src);
261
262		#endif /* SWSCALE_GRAPH_H */