FFmpeg
swscale.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2001-2011 Michael Niedermayer <michaelni@gmx.at>
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_SWSCALE_H
22 #define SWSCALE_SWSCALE_H
23 
24 /**
25  * @file
26  * @ingroup libsws
27  * external API header
28  */
29 
30 #include <stdint.h>
31 
32 #include "libavutil/avutil.h"
33 #include "libavutil/log.h"
34 #include "libavutil/pixfmt.h"
35 #include "version.h"
36 
37 /**
38  * @defgroup libsws libswscale
39  * Color conversion and scaling library.
40  *
41  * @{
42  *
43  * Return the LIBSWSCALE_VERSION_INT constant.
44  */
45 unsigned swscale_version(void);
46 
47 /**
48  * Return the libswscale build-time configuration.
49  */
50 const char *swscale_configuration(void);
51 
52 /**
53  * Return the libswscale license.
54  */
55 const char *swscale_license(void);
56 
57 /* values for the flags, the stuff on the command line is different */
58 #define SWS_FAST_BILINEAR 1
59 #define SWS_BILINEAR 2
60 #define SWS_BICUBIC 4
61 #define SWS_X 8
62 #define SWS_POINT 0x10
63 #define SWS_AREA 0x20
64 #define SWS_BICUBLIN 0x40
65 #define SWS_GAUSS 0x80
66 #define SWS_SINC 0x100
67 #define SWS_LANCZOS 0x200
68 #define SWS_SPLINE 0x400
69 
70 #define SWS_SRC_V_CHR_DROP_MASK 0x30000
71 #define SWS_SRC_V_CHR_DROP_SHIFT 16
72 
73 #define SWS_PARAM_DEFAULT 123456
74 
75 #define SWS_PRINT_INFO 0x1000
76 
77 //the following 3 flags are not completely implemented
78 //internal chrominance subsampling info
79 #define SWS_FULL_CHR_H_INT 0x2000
80 //input subsampling info
81 #define SWS_FULL_CHR_H_INP 0x4000
82 #define SWS_DIRECT_BGR 0x8000
83 #define SWS_ACCURATE_RND 0x40000
84 #define SWS_BITEXACT 0x80000
85 #define SWS_ERROR_DIFFUSION 0x800000
86 
87 #define SWS_MAX_REDUCE_CUTOFF 0.002
88 
89 #define SWS_CS_ITU709 1
90 #define SWS_CS_FCC 4
91 #define SWS_CS_ITU601 5
92 #define SWS_CS_ITU624 5
93 #define SWS_CS_SMPTE170M 5
94 #define SWS_CS_SMPTE240M 7
95 #define SWS_CS_DEFAULT 5
96 #define SWS_CS_BT2020 9
97 
98 /**
99  * Return a pointer to yuv<->rgb coefficients for the given colorspace
100  * suitable for sws_setColorspaceDetails().
101  *
102  * @param colorspace One of the SWS_CS_* macros. If invalid,
103  * SWS_CS_DEFAULT is used.
104  */
105 const int *sws_getCoefficients(int colorspace);
106 
107 // when used for filters they must have an odd number of elements
108 // coeffs cannot be shared between vectors
109 typedef struct SwsVector {
110  double *coeff; ///< pointer to the list of coefficients
111  int length; ///< number of coefficients in the vector
112 } SwsVector;
113 
114 // vectors can be shared
115 typedef struct SwsFilter {
120 } SwsFilter;
121 
122 struct SwsContext;
123 
124 /**
125  * Return a positive value if pix_fmt is a supported input format, 0
126  * otherwise.
127  */
129 
130 /**
131  * Return a positive value if pix_fmt is a supported output format, 0
132  * otherwise.
133  */
135 
136 /**
137  * @param[in] pix_fmt the pixel format
138  * @return a positive value if an endianness conversion for pix_fmt is
139  * supported, 0 otherwise.
140  */
142 
143 /**
144  * Allocate an empty SwsContext. This must be filled and passed to
145  * sws_init_context(). For filling see AVOptions, options.c and
146  * sws_setColorspaceDetails().
147  */
148 struct SwsContext *sws_alloc_context(void);
149 
150 /**
151  * Initialize the swscaler context sws_context.
152  *
153  * @return zero or positive value on success, a negative value on
154  * error
155  */
157 int sws_init_context(struct SwsContext *sws_context, SwsFilter *srcFilter, SwsFilter *dstFilter);
158 
159 /**
160  * Free the swscaler context swsContext.
161  * If swsContext is NULL, then does nothing.
162  */
163 void sws_freeContext(struct SwsContext *swsContext);
164 
165 /**
166  * Allocate and return an SwsContext. You need it to perform
167  * scaling/conversion operations using sws_scale().
168  *
169  * @param srcW the width of the source image
170  * @param srcH the height of the source image
171  * @param srcFormat the source image format
172  * @param dstW the width of the destination image
173  * @param dstH the height of the destination image
174  * @param dstFormat the destination image format
175  * @param flags specify which algorithm and options to use for rescaling
176  * @param param extra parameters to tune the used scaler
177  * For SWS_BICUBIC param[0] and [1] tune the shape of the basis
178  * function, param[0] tunes f(1) and param[1] f´(1)
179  * For SWS_GAUSS param[0] tunes the exponent and thus cutoff
180  * frequency
181  * For SWS_LANCZOS param[0] tunes the width of the window function
182  * @return a pointer to an allocated context, or NULL in case of error
183  * @note this function is to be removed after a saner alternative is
184  * written
185  */
187  int dstW, int dstH, enum AVPixelFormat dstFormat,
188  int flags, SwsFilter *srcFilter,
189  SwsFilter *dstFilter, const double *param);
190 
191 /**
192  * Scale the image slice in srcSlice and put the resulting scaled
193  * slice in the image in dst. A slice is a sequence of consecutive
194  * rows in an image.
195  *
196  * Slices have to be provided in sequential order, either in
197  * top-bottom or bottom-top order. If slices are provided in
198  * non-sequential order the behavior of the function is undefined.
199  *
200  * @param c the scaling context previously created with
201  * sws_getContext()
202  * @param srcSlice the array containing the pointers to the planes of
203  * the source slice
204  * @param srcStride the array containing the strides for each plane of
205  * the source image
206  * @param srcSliceY the position in the source image of the slice to
207  * process, that is the number (counted starting from
208  * zero) in the image of the first row of the slice
209  * @param srcSliceH the height of the source slice, that is the number
210  * of rows in the slice
211  * @param dst the array containing the pointers to the planes of
212  * the destination image
213  * @param dstStride the array containing the strides for each plane of
214  * the destination image
215  * @return the height of the output slice
216  */
217 int sws_scale(struct SwsContext *c, const uint8_t *const srcSlice[],
218  const int srcStride[], int srcSliceY, int srcSliceH,
219  uint8_t *const dst[], const int dstStride[]);
220 
221 /**
222  * @param dstRange flag indicating the while-black range of the output (1=jpeg / 0=mpeg)
223  * @param srcRange flag indicating the while-black range of the input (1=jpeg / 0=mpeg)
224  * @param table the yuv2rgb coefficients describing the output yuv space, normally ff_yuv2rgb_coeffs[x]
225  * @param inv_table the yuv2rgb coefficients describing the input yuv space, normally ff_yuv2rgb_coeffs[x]
226  * @param brightness 16.16 fixed point brightness correction
227  * @param contrast 16.16 fixed point contrast correction
228  * @param saturation 16.16 fixed point saturation correction
229  * @return -1 if not supported
230  */
231 int sws_setColorspaceDetails(struct SwsContext *c, const int inv_table[4],
232  int srcRange, const int table[4], int dstRange,
233  int brightness, int contrast, int saturation);
234 
235 /**
236  * @return -1 if not supported
237  */
238 int sws_getColorspaceDetails(struct SwsContext *c, int **inv_table,
239  int *srcRange, int **table, int *dstRange,
240  int *brightness, int *contrast, int *saturation);
241 
242 /**
243  * Allocate and return an uninitialized vector with length coefficients.
244  */
245 SwsVector *sws_allocVec(int length);
246 
247 /**
248  * Return a normalized Gaussian curve used to filter stuff
249  * quality = 3 is high quality, lower is lower quality.
250  */
251 SwsVector *sws_getGaussianVec(double variance, double quality);
252 
253 /**
254  * Scale all the coefficients of a by the scalar value.
255  */
256 void sws_scaleVec(SwsVector *a, double scalar);
257 
258 /**
259  * Scale all the coefficients of a so that their sum equals height.
260  */
261 void sws_normalizeVec(SwsVector *a, double height);
262 
263 void sws_freeVec(SwsVector *a);
264 
265 SwsFilter *sws_getDefaultFilter(float lumaGBlur, float chromaGBlur,
266  float lumaSharpen, float chromaSharpen,
267  float chromaHShift, float chromaVShift,
268  int verbose);
270 
271 /**
272  * Check if context can be reused, otherwise reallocate a new one.
273  *
274  * If context is NULL, just calls sws_getContext() to get a new
275  * context. Otherwise, checks if the parameters are the ones already
276  * saved in context. If that is the case, returns the current
277  * context. Otherwise, frees context and gets a new context with
278  * the new parameters.
279  *
280  * Be warned that srcFilter and dstFilter are not checked, they
281  * are assumed to remain the same.
282  */
284  int srcW, int srcH, enum AVPixelFormat srcFormat,
285  int dstW, int dstH, enum AVPixelFormat dstFormat,
286  int flags, SwsFilter *srcFilter,
287  SwsFilter *dstFilter, const double *param);
288 
289 /**
290  * Convert an 8-bit paletted frame into a frame with a color depth of 32 bits.
291  *
292  * The output frame will have the same packed format as the palette.
293  *
294  * @param src source frame buffer
295  * @param dst destination frame buffer
296  * @param num_pixels number of pixels to convert
297  * @param palette array with [256] entries, which must match color arrangement (RGB or BGR) of src
298  */
299 void sws_convertPalette8ToPacked32(const uint8_t *src, uint8_t *dst, int num_pixels, const uint8_t *palette);
300 
301 /**
302  * Convert an 8-bit paletted frame into a frame with a color depth of 24 bits.
303  *
304  * With the palette format "ABCD", the destination frame ends up with the format "ABC".
305  *
306  * @param src source frame buffer
307  * @param dst destination frame buffer
308  * @param num_pixels number of pixels to convert
309  * @param palette array with [256] entries, which must match color arrangement (RGB or BGR) of src
310  */
311 void sws_convertPalette8ToPacked24(const uint8_t *src, uint8_t *dst, int num_pixels, const uint8_t *palette);
312 
313 /**
314  * Get the AVClass for swsContext. It can be used in combination with
315  * AV_OPT_SEARCH_FAKE_OBJ for examining options.
316  *
317  * @see av_opt_find().
318  */
319 const AVClass *sws_get_class(void);
320 
321 /**
322  * @}
323  */
324 
325 #endif /* SWSCALE_SWSCALE_H */
sws_getCachedContext
struct SwsContext * sws_getCachedContext(struct SwsContext *context, int srcW, int srcH, enum AVPixelFormat srcFormat, int dstW, int dstH, enum AVPixelFormat dstFormat, int flags, SwsFilter *srcFilter, SwsFilter *dstFilter, const double *param)
Check if context can be reused, otherwise reallocate a new one.
Definition: utils.c:2301
SwsContext::saturation
int saturation
Definition: swscale_internal.h:421
AVPixelFormat
AVPixelFormat
Pixel format.
Definition: pixfmt.h:64
SwsContext::dstW
int dstW
Width of destination luma/alpha planes.
Definition: swscale_internal.h:481
table
static const uint16_t table[]
Definition: prosumer.c:206
SwsContext::srcRange
int srcRange
0 = MPG YUV range, 1 = JPG YUV range (source image).
Definition: swscale_internal.h:424
sws_scale
int sws_scale(struct SwsContext *c, const uint8_t *const srcSlice[], const int srcStride[], int srcSliceY, int srcSliceH, uint8_t *const dst[], const int dstStride[])
Scale the image slice in srcSlice and put the resulting scaled slice in the image in dst.
Definition: swscale.c:745
filter
filter_frame For filters that do not use the this method is called when a frame is pushed to the filter s input It can be called at any time except in a reentrant way If the input frame is enough to produce then the filter should push the output frames on the output link immediately As an exception to the previous rule if the input frame is enough to produce several output frames then the filter needs output only at least one per link The additional frames can be left buffered in the filter
Definition: filter_design.txt:228
sws_convertPalette8ToPacked24
void sws_convertPalette8ToPacked24(const uint8_t *src, uint8_t *dst, int num_pixels, const uint8_t *palette)
Convert an 8-bit paletted frame into a frame with a color depth of 24 bits.
Definition: swscale_unscaled.c:2242
quality
trying all byte sequences megabyte in length and selecting the best looking sequence will yield cases to try But a word about quality
Definition: rate_distortion.txt:12
sws_freeVec
void sws_freeVec(SwsVector *a)
Definition: utils.c:2220
swscale_license
const char * swscale_license(void)
Return the libswscale license.
Definition: utils.c:79
sws_get_class
const AVClass * sws_get_class(void)
Get the AVClass for swsContext.
Definition: options.c:95
SwsContext::srcFormat
enum AVPixelFormat srcFormat
Source pixel format.
Definition: swscale_internal.h:304
SwsContext::brightness
int brightness
Definition: swscale_internal.h:421
SwsVector::length
int length
number of coefficients in the vector
Definition: swscale.h:111
sws_allocVec
SwsVector * sws_allocVec(int length)
Allocate and return an uninitialized vector with length coefficients.
Definition: utils.c:2030
pix_fmt
static enum AVPixelFormat pix_fmt
Definition: demuxing_decoding.c:40
sws_getGaussianVec
SwsVector * sws_getGaussianVec(double variance, double quality)
Return a normalized Gaussian curve used to filter stuff quality = 3 is high quality,...
Definition: utils.c:2047
SwsContext::contrast
int contrast
Definition: swscale_internal.h:421
SwsContext::dstFormat
enum AVPixelFormat dstFormat
Destination pixel format.
Definition: swscale_internal.h:303
context
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 default minimum maximum flags name is the option keep it simple and lowercase description are in without and describe what they for example set the foo of the bar offset is the offset of the field in your context
Definition: writing_filters.txt:91
AVClass
Describe the class of an AVClass context structure.
Definition: log.h:67
sws_getDefaultFilter
SwsFilter * sws_getDefaultFilter(float lumaGBlur, float chromaGBlur, float lumaSharpen, float chromaSharpen, float chromaHShift, float chromaVShift, int verbose)
Definition: utils.c:1947
src
#define src
Definition: vp8dsp.c:255
sws_alloc_context
struct SwsContext * sws_alloc_context(void)
Allocate an empty SwsContext.
Definition: utils.c:1086
SwsVector::coeff
double * coeff
pointer to the list of coefficients
Definition: swscale.h:110
sws_setColorspaceDetails
int sws_setColorspaceDetails(struct SwsContext *c, const int inv_table[4], int srcRange, const int table[4], int dstRange, int brightness, int contrast, int saturation)
Definition: utils.c:865
sws_scaleVec
void sws_scaleVec(SwsVector *a, double scalar)
Scale all the coefficients of a by the scalar value.
Definition: utils.c:2113
c
Undefined Behavior In the C some operations are like signed integer dereferencing freed accessing outside allocated Undefined Behavior must not occur in a C it is not safe even if the output of undefined operations is unused The unsafety may seem nit picking but Optimizing compilers have in fact optimized code on the assumption that no undefined Behavior occurs Optimizing code based on wrong assumptions can and has in some cases lead to effects beyond the output of computations The signed integer overflow problem in speed critical code Code which is highly optimized and works with signed integers sometimes has the problem that often the output of the computation does not c
Definition: undefined.txt:32
SwsFilter::chrV
SwsVector * chrV
Definition: swscale.h:119
SwsVector
Definition: swscale.h:109
sws_getContext
struct SwsContext * sws_getContext(int srcW, int srcH, enum AVPixelFormat srcFormat, int dstW, int dstH, enum AVPixelFormat dstFormat, int flags, SwsFilter *srcFilter, SwsFilter *dstFilter, const double *param)
Allocate and return an SwsContext.
Definition: utils.c:1910
SwsContext::srcH
int srcH
Height of source luma/alpha planes.
Definition: swscale_internal.h:295
srcSliceH
return srcSliceH
Definition: yuv2rgb_template.c:87
SwsFilter
Definition: swscale.h:115
height
#define height
a
The reader does not expect b to be semantically here and if the code is changed by maybe adding a a division or other the signedness will almost certainly be mistaken To avoid this confusion a new type was SUINT is the C unsigned type but it holds a signed int to use the same example SUINT a
Definition: undefined.txt:41
SwsFilter::lumV
SwsVector * lumV
Definition: swscale.h:117
swscale_configuration
const char * swscale_configuration(void)
Return the libswscale build-time configuration.
Definition: utils.c:74
sws_isSupportedInput
int sws_isSupportedInput(enum AVPixelFormat pix_fmt)
Return a positive value if pix_fmt is a supported input format, 0 otherwise.
Definition: utils.c:270
av_warn_unused_result
#define av_warn_unused_result
Definition: attributes.h:64
SwsContext::srcW
int srcW
Width of source luma/alpha planes.
Definition: swscale_internal.h:294
sws_isSupportedEndiannessConversion
int sws_isSupportedEndiannessConversion(enum AVPixelFormat pix_fmt)
Definition: utils.c:282
log.h
SwsContext::dstRange
int dstRange
0 = MPG YUV range, 1 = JPG YUV range (destination image).
Definition: swscale_internal.h:425
sws_isSupportedOutput
int sws_isSupportedOutput(enum AVPixelFormat pix_fmt)
Return a positive value if pix_fmt is a supported output format, 0 otherwise.
Definition: utils.c:276
sws_freeFilter
void sws_freeFilter(SwsFilter *filter)
Definition: utils.c:2229
version.h
pixfmt.h
verbose
int verbose
Definition: checkasm.c:286
sws_getColorspaceDetails
int sws_getColorspaceDetails(struct SwsContext *c, int **inv_table, int *srcRange, int **table, int *dstRange, int *brightness, int *contrast, int *saturation)
Definition: utils.c:1000
sws_init_context
av_warn_unused_result int sws_init_context(struct SwsContext *sws_context, SwsFilter *srcFilter, SwsFilter *dstFilter)
Initialize the swscaler context sws_context.
Definition: utils.c:1172
sws_freeContext
void sws_freeContext(struct SwsContext *swsContext)
Free the swscaler context swsContext.
Definition: utils.c:2241
avutil.h
sws_getCoefficients
const int * sws_getCoefficients(int colorspace)
Return a pointer to yuv<->rgb coefficients for the given colorspace suitable for sws_setColorspaceDet...
Definition: yuv2rgb.c:63
swscale_version
unsigned swscale_version(void)
Definition: utils.c:68
SwsFilter::lumH
SwsVector * lumH
Definition: swscale.h:116
flags
#define flags(name, subs,...)
Definition: cbs_av1.c:561
sws_convertPalette8ToPacked32
void sws_convertPalette8ToPacked32(const uint8_t *src, uint8_t *dst, int num_pixels, const uint8_t *palette)
Convert an 8-bit paletted frame into a frame with a color depth of 32 bits.
Definition: swscale_unscaled.c:2232
SwsContext
Definition: swscale_internal.h:283
SwsFilter::chrH
SwsVector * chrH
Definition: swscale.h:118
SwsContext::dstH
int dstH
Height of destination luma/alpha planes.
Definition: swscale_internal.h:296
sws_normalizeVec
void sws_normalizeVec(SwsVector *a, double height)
Scale all the coefficients of a so that their sum equals height.
Definition: utils.c:2121
SwsContext::param
double param[2]
Input parameters for scaling algorithms that need them.
Definition: swscale_internal.h:314