FFmpeg
Loading...
Searching...
No Matches
ops.h
Go to the documentation of this file.
1/**
2 * Copyright (C) 2025 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_OPS_H
22#define SWSCALE_OPS_H
23
24#include <assert.h>
25#include <stdbool.h>
26#include <stdalign.h>
27
28#include "libavutil/bprint.h"
29
30#include "graph.h"
31#include "filters.h"
32#include "lut3d.h"
33#include "rational64.h"
34#include "uops.h"
35
36typedef enum SwsOpType {
38
39 /* Defined for all types; but implemented for integers only */
40 SWS_OP_READ, /* gather raw pixels from planes */
41 SWS_OP_WRITE, /* write raw pixels to planes */
42 SWS_OP_SWAP_BYTES, /* swap byte order (for differing endianness) */
43 SWS_OP_SWIZZLE, /* rearrange channel order, or duplicate channels */
44
45 /* Bit manipulation operations. Defined for integers only. */
46 SWS_OP_UNPACK, /* split tightly packed data into components */
47 SWS_OP_PACK, /* compress components into tightly packed data */
48 SWS_OP_LSHIFT, /* logical left shift of raw pixel values */
49 SWS_OP_RSHIFT, /* right shift of raw pixel values */
50
51 /* Generic arithmetic. Defined and implemented for all types */
52 SWS_OP_CLEAR, /* clear pixel values */
53 SWS_OP_CONVERT, /* convert (cast) between formats */
54 SWS_OP_MIN, /* numeric minimum */
55 SWS_OP_MAX, /* numeric maximum */
56 SWS_OP_SCALE, /* multiplication by scalar */
57 SWS_OP_LINEAR, /* generalized linear affine transform */
58
59 /* Floating-point only arithmetic operations. */
60 SWS_OP_DITHER, /* add dithering noise */
61
62 /* Filtering operations. */
63 SWS_OP_FILTER_H, /* horizontal filtering */
64 SWS_OP_FILTER_V, /* vertical filtering */
65
66 /* Table-based operations. Defined for floating point types only. */
67 SWS_OP_LUT_3D, /* apply a SwsLut3D */
68
70} SwsOpType;
71
73
74/* Compute SwsCompMask from values with denominator != 0 */
76
77typedef enum SwsReadWriteMode {
78 /**
79 * Note: 1-component reads are either SWS_RW_PLANAR or SWS_RW_PACKED,
80 * depending on the underlying interpretation. If multiple components are
81 * packed into one element (e.g. rgb10a2 -> u16), they are marked as
82 * SWS_RW_PACKED. Otherwise (e.g. gray16le), they are SWS_RW_PLANAR.
83 *
84 * This is a purely semantic/informative difference; the underlying code
85 * treats 1-components reads/writes the same regardless of mode.
86 */
87 SWS_RW_PLANAR, /* one plane per component */
88 SWS_RW_PACKED, /* all components on a single plane */
89 SWS_RW_PALETTE, /* plane 0 is 8-bit index, plane 1 is packed palette */
91
92typedef struct SwsReadWriteOp {
93 /**
94 * Examples:
95 * rgba = 4x u8 packed
96 * yuv444p = 3x u8
97 * rgb565 = 1x u16 <- use SWS_OP_UNPACK to unpack
98 * monow = 1x u8 (frac 3)
99 * rgb4 = 1x u8 (frac 1)
100 * pal8 = 4x u8 (palette)
101 */
102 SwsPixelType type; /* pixel type to read */
103 SwsReadWriteMode mode; /* how data is laid out in memory */
104 uint8_t elems; /* number of elements (of type `op.type`) to read/write */
105 uint8_t frac; /* fractional pixel step factor (log2) */
106
107 /**
108 * Filter kernel to apply to each plane while sampling. Currently, only
109 * one shared filter kernel is supported for all planes. (Optional)
110 *
111 * Note: As with SWS_OP_FILTER_*, if a filter kernel is in use, the read
112 * operation will always output floating point values.
113 */
114 struct {
115 SwsOpType op; /* some value of SWS_OP_FILTER_* */
116 SwsFilterWeights *kernel; /* (refstruct) */
117 SwsPixelType type; /* pixel type to store result as */
120
121typedef struct SwsPackOp {
122 /**
123 * Packed bits are assumed to be LSB-aligned within the underlying
124 * integer type; i.e. (msb) 0 ... X Y Z W (lsb).
125 */
126 uint8_t pattern[4]; /* bit depth pattern, from MSB to LSB */
127} SwsPackOp;
128
129typedef struct SwsSwizzleOp {
130 /**
131 * Input component for each output component:
132 * Out[x] := In[swizzle.in[x]]
133 */
134 union {
135 uint32_t mask;
136 uint8_t in[4];
137 struct { uint8_t x, y, z, w; };
138 };
140
141#define SWS_SWIZZLE(X,Y,Z,W) ((SwsSwizzleOp) { .in = {X, Y, Z, W} })
143
144typedef struct SwsShiftOp {
145 uint8_t amount; /* number of bits to shift */
146} SwsShiftOp;
147
148typedef struct SwsClearOp {
149 SwsPixelType type[4]; /* type of each value */
150 SwsCompMask mask; /* mask of components to clear */
151 AVRational64 value[4]; /* value to set */
152} SwsClearOp;
153
154typedef struct SwsConvertOp {
155 SwsPixelType to; /* type of pixel to convert to */
157
158typedef struct SwsClampOp {
159 AVRational64 limit[4]; /* per-component min/max value */
160} SwsClampOp;
161
162typedef struct SwsScaleOp {
163 AVRational64 factor; /* scalar multiplication factor */
164} SwsScaleOp;
165
166typedef struct SwsDitherOp {
167 AVRational64 *matrix; /* tightly packed dither matrix (refstruct) */
168 AVRational64 min, max; /* minimum/maximum value in `matrix` */
169 int size_log2; /* size (in bits) of the dither matrix */
170 int8_t y_offset[4]; /* row offset for each component, or -1 for ignored */
172
173typedef struct SwsLinearOp {
174 /**
175 * Pixel type per output component. This must match the type of incoming
176 * values, as determined by the weights matrix.
177 */
179
180 /**
181 * Generalized 5x5 affine transformation:
182 * [ Out.x ] = [ A B C D E ]
183 * [ Out.y ] = [ F G H I J ] * [ x y z w 1 ]
184 * [ Out.z ] = [ K L M N O ]
185 * [ Out.w ] = [ P Q R S T ]
186 *
187 * Note: For integer types, these entries may exceed the value range of
188 * the pixel type itself. It's implied that implementations will perform
189 * all intermediate calculations modulo 2^N where N is the bit depth of
190 * the pixel type, including the final result.
191 */
194
195/* m[i][j] <-> 1 << (5 * i + j) */
196uint32_t ff_sws_linear_mask(const SwsLinearOp *c);
197
198typedef struct SwsFilterOp {
199 SwsFilterWeights *kernel; /* filter kernel (refstruct) */
200 SwsPixelType type; /* pixel type to store result as */
202
203typedef struct SwsLut3dOp {
204 /**
205 * Reference to the external LUT3D to apply. This is managed by the caller,
206 * and must remain valid for the lifetime of the SwsOp and any compiled
207 * functions derived from it.
208 *
209 * *lut is never dereferenced by the SwsOp code itself, only at runtime by
210 * the actual dispatched implementation, and may be freely modified even
211 * after op compilation to place new values for dynamic tone-mapping.
212 *
213 * The reference algorithm for this operation lives in lut3d.c, and
214 * includes a tetrahedral interpolation component for the input LUT, and
215 * then an optional linear tone mapping LUT plus trilinear output LUT
216 * (when lut->dynamic is true).
217 *
218 * All linear interpolations are performed in the pixel value's native
219 * representation, even though the LUTs themselves are stored as unsigned
220 * packed 16-bit integers. The input value range is assumed to be scaled
221 * and clamped to the LUT's domain (i.e. [0, INPUT_LUT_SIZE - 1]), and the
222 * output value range will be [0, 2^16-1], except for the alpha channel,
223 * which is passed through untouched.
224 */
225 const SwsLut3D *lut; /* refstruct */
227} SwsLut3dOp;
228
229typedef enum SwsCompFlags {
230 SWS_COMP_EXACT = 1 << 0, /* value is an exact integer */
231 SWS_COMP_ZERO = 1 << 1, /* known to be a constant zero */
232 SWS_COMP_SWAPPED = 1 << 2, /* byte order is swapped */
233 SWS_COMP_COPY = 1 << 3, /* value is unmodified from the source plane */
234 SWS_COMP_CONST = 1 << 4, /* value is a fixed constant */
236
237typedef struct SwsOpPad {
238 SwsPixelType type; /* pixel type of this output component */
239 SwsCompFlags flags; /* knowledge about component contents */
240
241 /* Keeps track of the known possible value range, or {0, 0} for undefined
242 * or (unknown range) floating point inputs */
244
245 /* Keeps track of input (forward) and output (reverse) dependencies */
247} SwsOpPad;
248
249typedef struct SwsOp SwsOp;
250typedef struct SwsOpList SwsOpList;
251
252struct SwsOp {
254 union {
267 };
268
269 /**
270 * Metadata about the operation's input/output components. Discarded
271 * and regenerated automatically by `ff_sws_op_list_update()`.
272 *
273 * Note that backends may rely on the presence and accuracy of this
274 * metadata for all operations, during ff_sws_ops_compile().
275 */
277
278 /* Link back to the SwsOpList that owns this operation */
280};
281
282#define SWS_OP_NEEDED(op, idx) ((op)->outputs[idx].dep_out != 0)
283
284/* Compute SwsCompMask from a mask of needed components */
286
287/**
288 * Return the number of planes involved in a read/write operation.
289 */
290int ff_sws_rw_op_planes(const SwsOp *op);
291
292/**
293 * Return the input/output type of an operation, if all inputs/outputs are
294 * the same type, or SWS_PIXEL_NONE if no type can be established.
295 */
298
299/**
300 * Describe an operation in human-readable form.
301 */
302void ff_sws_op_desc(AVBPrint *bp, const SwsOp *op);
303
304/**
305 * Apply an operation to an AVRational64. No-op for read/write operations.
306 */
307void ff_sws_apply_op_q(const SwsOp *op, AVRational64 x[4]);
308
309/**
310 * Return the previous/next operation in the list, or NULL if there is none.
311 */
312const SwsOp *ff_sws_op_prev(const SwsOp *op);
313const SwsOp *ff_sws_op_next(const SwsOp *op);
314
315/**
316 * Helper struct for representing a list of operations.
317 */
318typedef struct SwsOpList {
321
322 /* Metadata associated with this operation list */
324
325 /* Input/output plane indices */
326 uint8_t plane_src[4], plane_dst[4];
327
328 /**
329 * Source component metadata associated with pixel values from each
330 * corresponding component (in plane/memory order, i.e. not affected by
331 * `plane_src`). Lets the optimizer know additional information about
332 * the value range and/or pixel data to expect.
333 *
334 * The default value of {0} is safe to pass in the case that no additional
335 * information is known.
336 */
338} SwsOpList;
339
342
343/**
344 * Returns a duplicate of `ops`, or NULL on OOM.
345 */
347
348/**
349 * Returns the input operation for a given op list, or NULL if there is none
350 * (e.g. for a pure CLEAR-only operation list).
351 *
352 * This will always be an op of type SWS_OP_READ.
353 */
354const SwsOp *ff_sws_op_list_input(const SwsOpList *ops);
355
356/**
357 * Returns the output operation for a given op list, or NULL if there is none.
358 *
359 * This will always be an op of type SWS_OP_WRITE.
360 */
361const SwsOp *ff_sws_op_list_output(const SwsOpList *ops);
362
363/**
364 * Returns whether an op list represents a true no-op operation, i.e. may be
365 * eliminated entirely from an execution graph.
366 */
367bool ff_sws_op_list_is_noop(const SwsOpList *ops);
368
369/**
370 * These will take over ownership of `op` and set it to {0}, even on failure.
371 */
374
375void ff_sws_op_list_remove_at(SwsOpList *ops, int index, int count);
376
377/**
378 * Print out the contents of an operation list.
379 *
380 * Note: This requires having called `ff_sws_op_list_update()` to
381 * refresh the output pads, or the output may be stale/missing.
382 */
383void ff_sws_op_list_print(void *log_ctx, int log_level, int log_level_extra,
384 const SwsOpList *ops);
385
386/**
387 * Infer + propagate known information about components. Called automatically
388 * when needed by the optimizer and compiler.
389 */
391
392/**
393 * Fuse compatible and eliminate redundant operations, as well as replacing
394 * some operations with more efficient alternatives.
395 */
397
398#endif
AVBPrint public header.
int index
Definition gxfenc.c:90
static int op(uint8_t **dst, const uint8_t *dst_end, GetByteContext *gb, int pixel, int count, int *x, int width, int linesize)
Perform decode operation.
Definition anm.c:76
static const uint16_t mask[17]
Definition lzw.c:38
void ff_sws_op_desc(AVBPrint *bp, const SwsOp *op)
Describe an operation in human-readable form.
Definition ops.c:932
SwsPixelType ff_sws_op_output_type(const SwsOp *op)
Definition ops.c:171
int ff_sws_op_list_optimize(SwsOpList *ops)
Fuse compatible and eliminate redundant operations, as well as replacing some operations with more ef...
const SwsOp * ff_sws_op_next(const SwsOp *op)
Definition ops.c:162
uint32_t ff_sws_linear_mask(const SwsLinearOp *c)
Definition ops.c:861
int ff_sws_op_list_insert_at(SwsOpList *ops, int index, SwsOp *op)
Definition ops.c:811
void ff_sws_op_list_print(void *log_ctx, int log_level, int log_level_extra, const SwsOpList *ops)
Print out the contents of an operation list.
Definition ops.c:1041
const SwsOp * ff_sws_op_list_input(const SwsOpList *ops)
Returns the input operation for a given op list, or NULL if there is none (e.g.
Definition ops.c:782
void ff_sws_op_list_update(SwsOpList *ops)
Infer + propagate known information about components.
Definition ops.c:677
int ff_sws_op_list_append(SwsOpList *ops, SwsOp *op)
These will take over ownership of op and set it to {0}, even on failure.
Definition ops.c:826
void ff_sws_comp_mask_swizzle(SwsCompMask *mask, const SwsSwizzleOp *swiz)
Definition ops.c:110
SwsOpList * ff_sws_op_list_alloc(void)
Definition ops.c:730
const char * ff_sws_op_type_name(SwsOpType op)
Definition ops.c:71
SwsPixelType ff_sws_op_input_type(const SwsOp *op)
Return the input/output type of an operation, if all inputs/outputs are the same type,...
Definition ops.c:186
SwsCompMask ff_sws_comp_mask_needed(const SwsOp *op)
Definition ops.c:123
SwsCompMask ff_sws_comp_mask_q4(const AVRational64 q[4])
Definition ops.c:100
int ff_sws_rw_op_planes(const SwsOp *op)
Return the number of planes involved in a read/write operation.
Definition ops.c:133
const SwsOp * ff_sws_op_list_output(const SwsOpList *ops)
Returns the output operation for a given op list, or NULL if there is none.
Definition ops.c:791
bool ff_sws_op_list_is_noop(const SwsOpList *ops)
Returns whether an op list represents a true no-op operation, i.e.
Definition ops.c:831
const SwsOp * ff_sws_op_prev(const SwsOp *op)
Return the previous/next operation in the list, or NULL if there is none.
Definition ops.c:153
SwsOpType
Copyright (C) 2025 Niklas Haas.
Definition ops.h:36
@ SWS_OP_TYPE_NB
Definition ops.h:69
@ SWS_OP_INVALID
Definition ops.h:37
@ SWS_OP_RSHIFT
Definition ops.h:49
@ SWS_OP_SWIZZLE
Definition ops.h:43
@ SWS_OP_LSHIFT
Definition ops.h:48
@ SWS_OP_FILTER_V
Definition ops.h:64
@ SWS_OP_SCALE
Definition ops.h:56
@ SWS_OP_FILTER_H
Definition ops.h:63
@ SWS_OP_WRITE
Definition ops.h:41
@ SWS_OP_READ
Definition ops.h:40
@ SWS_OP_CLEAR
Definition ops.h:52
@ SWS_OP_SWAP_BYTES
Definition ops.h:42
@ SWS_OP_MIN
Definition ops.h:54
@ SWS_OP_UNPACK
Definition ops.h:46
@ SWS_OP_LINEAR
Definition ops.h:57
@ SWS_OP_PACK
Definition ops.h:47
@ SWS_OP_DITHER
Definition ops.h:60
@ SWS_OP_MAX
Definition ops.h:55
@ SWS_OP_LUT_3D
Definition ops.h:67
@ SWS_OP_CONVERT
Definition ops.h:53
SwsReadWriteMode
Definition ops.h:77
@ SWS_RW_PALETTE
Definition ops.h:89
@ SWS_RW_PLANAR
Note: 1-component reads are either SWS_RW_PLANAR or SWS_RW_PACKED, depending on the underlying interp...
Definition ops.h:87
@ SWS_RW_PACKED
Definition ops.h:88
SwsCompFlags
Definition ops.h:229
@ SWS_COMP_CONST
Definition ops.h:234
@ SWS_COMP_ZERO
Definition ops.h:231
@ SWS_COMP_EXACT
Definition ops.h:230
@ SWS_COMP_SWAPPED
Definition ops.h:232
@ SWS_COMP_COPY
Definition ops.h:233
void ff_sws_apply_op_q(const SwsOp *op, AVRational64 x[4])
Apply an operation to an AVRational64.
Definition ops.c:202
void ff_sws_op_list_remove_at(SwsOpList *ops, int index, int count)
Definition ops.c:800
SwsOpList * ff_sws_op_list_duplicate(const SwsOpList *ops)
Returns a duplicate of ops, or NULL on OOM.
Definition ops.c:757
void ff_sws_op_list_free(SwsOpList **ops)
Definition ops.c:743
64-bit extension of AVRational.
64-bit Rational number (pair of numerator and denominator).
Definition rational64.h:52
AVRational64 limit[4]
Definition ops.h:159
SwsPixelType type[4]
Definition ops.h:149
SwsCompMask mask
Definition ops.h:150
AVRational64 value[4]
Definition ops.h:151
SwsPixelType to
Definition ops.h:155
AVRational64 min
Definition ops.h:168
AVRational64 * matrix
Definition ops.h:167
AVRational64 max
Definition ops.h:168
int size_log2
Definition ops.h:169
int8_t y_offset[4]
Definition ops.h:170
SwsPixelType type
Definition ops.h:200
SwsFilterWeights * kernel
Definition ops.h:199
Represents a computed filter kernel.
Definition filters.h:91
SwsPixelType type[4]
Pixel type per output component.
Definition ops.h:178
AVRational64 m[4][5]
Generalized 5x5 affine transformation: [ Out.x ] = [ A B C D E ] [ Out.y ] = [ F G H I J ] * [ x y z ...
Definition ops.h:192
const SwsLut3D * lut
Reference to the external LUT3D to apply.
Definition ops.h:225
bool dynamic
Definition ops.h:226
Helper struct for representing a list of operations.
Definition ops.h:318
SwsFormat dst
Definition ops.h:323
uint8_t plane_src[4]
Definition ops.h:326
uint8_t plane_dst[4]
Definition ops.h:326
SwsOp * ops
Definition ops.h:319
SwsOpPad inputs[4]
Source component metadata associated with pixel values from each corresponding component (in plane/me...
Definition ops.h:337
int num_ops
Definition ops.h:320
SwsFormat src
Definition ops.h:323
SwsCompMask dep_in
Definition ops.h:246
SwsCompFlags flags
Definition ops.h:239
AVRational64 min
Definition ops.h:243
AVRational64 max
Definition ops.h:243
SwsCompMask dep_out
Definition ops.h:246
SwsPixelType type
Definition ops.h:238
Definition ops.h:252
SwsClampOp clamp
Definition ops.h:262
SwsScaleOp scale
Definition ops.h:263
SwsSwizzleOp swizzle
Definition ops.h:258
SwsOpType op
Definition ops.h:253
SwsConvertOp convert
Definition ops.h:261
SwsPackOp pack
Definition ops.h:257
SwsClearOp clear
Definition ops.h:260
SwsLinearOp lin
Definition ops.h:255
SwsReadWriteOp rw
Definition ops.h:256
SwsFilterOp filter
Definition ops.h:265
SwsOpPad outputs[4]
Metadata about the operation's input/output components.
Definition ops.h:276
SwsLut3dOp lut3d
Definition ops.h:266
SwsOpList * ops
Definition ops.h:279
SwsShiftOp shift
Definition ops.h:259
SwsDitherOp dither
Definition ops.h:264
uint8_t pattern[4]
Packed bits are assumed to be LSB-aligned within the underlying integer type; i.e.
Definition ops.h:126
SwsFilterWeights * kernel
Definition ops.h:116
SwsReadWriteMode mode
Definition ops.h:103
SwsPixelType type
Examples: rgba = 4x u8 packed yuv444p = 3x u8 rgb565 = 1x u16 <- use SWS_OP_UNPACK to unpack monow = ...
Definition ops.h:102
SwsOpType op
Definition ops.h:115
uint8_t frac
Definition ops.h:105
uint8_t elems
Definition ops.h:104
AVRational64 factor
Definition ops.h:163
uint8_t amount
Definition ops.h:145
uint8_t x
Definition ops.h:137
uint8_t z
Definition ops.h:137
uint8_t w
Definition ops.h:137
uint8_t in[4]
Definition ops.h:136
uint32_t mask
Definition ops.h:135
uint8_t y
Definition ops.h:137
void(* filter)(uint8_t *src, ptrdiff_t stride, int qscale)
Definition h263dsp.c:29
SwsPixelType
Definition uops.h:40
uint8_t SwsCompMask
Bit-mask of components.
Definition uops.h:129
static double c[64]