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 #if FF_API_SWS_VECTOR
264 attribute_deprecated SwsVector *sws_getConstVec(double c, int length);
271 attribute_deprecated void sws_printVec2(SwsVector *a, AVClass *log_ctx, int log_level);
272 #endif
273 
274 void sws_freeVec(SwsVector *a);
275 
276 SwsFilter *sws_getDefaultFilter(float lumaGBlur, float chromaGBlur,
277  float lumaSharpen, float chromaSharpen,
278  float chromaHShift, float chromaVShift,
279  int verbose);
281 
282 /**
283  * Check if context can be reused, otherwise reallocate a new one.
284  *
285  * If context is NULL, just calls sws_getContext() to get a new
286  * context. Otherwise, checks if the parameters are the ones already
287  * saved in context. If that is the case, returns the current
288  * context. Otherwise, frees context and gets a new context with
289  * the new parameters.
290  *
291  * Be warned that srcFilter and dstFilter are not checked, they
292  * are assumed to remain the same.
293  */
295  int srcW, int srcH, enum AVPixelFormat srcFormat,
296  int dstW, int dstH, enum AVPixelFormat dstFormat,
297  int flags, SwsFilter *srcFilter,
298  SwsFilter *dstFilter, const double *param);
299 
300 /**
301  * Convert an 8-bit paletted frame into a frame with a color depth of 32 bits.
302  *
303  * The output frame will have the same packed format as the palette.
304  *
305  * @param src source frame buffer
306  * @param dst destination frame buffer
307  * @param num_pixels number of pixels to convert
308  * @param palette array with [256] entries, which must match color arrangement (RGB or BGR) of src
309  */
310 void sws_convertPalette8ToPacked32(const uint8_t *src, uint8_t *dst, int num_pixels, const uint8_t *palette);
311 
312 /**
313  * Convert an 8-bit paletted frame into a frame with a color depth of 24 bits.
314  *
315  * With the palette format "ABCD", the destination frame ends up with the format "ABC".
316  *
317  * @param src source frame buffer
318  * @param dst destination frame buffer
319  * @param num_pixels number of pixels to convert
320  * @param palette array with [256] entries, which must match color arrangement (RGB or BGR) of src
321  */
322 void sws_convertPalette8ToPacked24(const uint8_t *src, uint8_t *dst, int num_pixels, const uint8_t *palette);
323 
324 /**
325  * Get the AVClass for swsContext. It can be used in combination with
326  * AV_OPT_SEARCH_FAKE_OBJ for examining options.
327  *
328  * @see av_opt_find().
329  */
330 const AVClass *sws_get_class(void);
331 
332 /**
333  * @}
334  */
335 
336 #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:2379
SwsContext::saturation
int saturation
Definition: swscale_internal.h:418
AVPixelFormat
AVPixelFormat
Pixel format.
Definition: pixfmt.h:64
SwsContext::dstW
int dstW
Width of destination luma/alpha planes.
Definition: swscale_internal.h:478
sws_addVec
attribute_deprecated void sws_addVec(SwsVector *a, SwsVector *b)
Definition: utils.c:2212
b
#define b
Definition: input.c:41
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:421
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:744
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:2192
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:2298
sws_getConstVec
attribute_deprecated SwsVector * sws_getConstVec(double c, int length)
Allocate and return a vector with length coefficients, all with the same value c.
Definition: utils.c:2069
swscale_license
const char * swscale_license(void)
Return the libswscale license.
Definition: utils.c:86
sws_get_class
const AVClass * sws_get_class(void)
Get the AVClass for swsContext.
Definition: options.c:95
sws_printVec2
attribute_deprecated void sws_printVec2(SwsVector *a, AVClass *log_ctx, int log_level)
Print with av_log() a textual representation of the vector a if log_level <= av_log_level.
Definition: utils.c:2272
SwsContext::srcFormat
enum AVPixelFormat srcFormat
Source pixel format.
Definition: swscale_internal.h:301
SwsContext::brightness
int brightness
Definition: swscale_internal.h:418
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:2019
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:2036
SwsContext::contrast
int contrast
Definition: swscale_internal.h:418
SwsContext::dstFormat
enum AVPixelFormat dstFormat
Destination pixel format.
Definition: swscale_internal.h:300
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:1936
src
#define src
Definition: vp8dsp.c:254
sws_alloc_context
struct SwsContext * sws_alloc_context(void)
Allocate an empty SwsContext.
Definition: utils.c:1084
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:863
sws_cloneVec
attribute_deprecated SwsVector * sws_cloneVec(SwsVector *a)
Definition: utils.c:2252
sws_scaleVec
void sws_scaleVec(SwsVector *a, double scalar)
Scale all the coefficients of a by the scalar value.
Definition: utils.c:2106
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
sws_subVec
attribute_deprecated void sws_subVec(SwsVector *a, SwsVector *b)
Definition: utils.c:2226
sws_convVec
attribute_deprecated void sws_convVec(SwsVector *a, SwsVector *b)
Definition: utils.c:2239
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:1899
SwsContext::srcH
int srcH
Height of source luma/alpha planes.
Definition: swscale_internal.h:292
srcSliceH
return srcSliceH
Definition: yuv2rgb_template.c:87
attribute_deprecated
#define attribute_deprecated
Definition: attributes.h:104
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:81
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:276
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:291
sws_isSupportedEndiannessConversion
int sws_isSupportedEndiannessConversion(enum AVPixelFormat pix_fmt)
Definition: utils.c:288
log.h
SwsContext::dstRange
int dstRange
0 = MPG YUV range, 1 = JPG YUV range (destination image).
Definition: swscale_internal.h:422
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:282
uint8_t
uint8_t
Definition: audio_convert.c:194
sws_freeFilter
void sws_freeFilter(SwsFilter *filter)
Definition: utils.c:2307
version.h
pixfmt.h
verbose
int verbose
Definition: checkasm.c:272
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:998
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:1170
sws_freeContext
void sws_freeContext(struct SwsContext *swsContext)
Free the swscaler context swsContext.
Definition: utils.c:2319
shift
static int shift(int a, int b)
Definition: sonic.c:82
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:75
SwsFilter::lumH
SwsVector * lumH
Definition: swscale.h:116
flags
#define flags(name, subs,...)
Definition: cbs_av1.c:565
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:2182
SwsContext
Definition: swscale_internal.h:280
SwsFilter::chrH
SwsVector * chrH
Definition: swscale.h:118
SwsContext::dstH
int dstH
Height of destination luma/alpha planes.
Definition: swscale_internal.h:293
sws_normalizeVec
void sws_normalizeVec(SwsVector *a, double height)
Scale all the coefficients of a so that their sum equals height.
Definition: utils.c:2114
sws_getIdentityVec
attribute_deprecated SwsVector * sws_getIdentityVec(void)
Allocate and return a vector with just one coefficient, with value 1.0.
Definition: utils.c:2090
SwsContext::param
double param[2]
Input parameters for scaling algorithms that need them.
Definition: swscale_internal.h:311
sws_shiftVec
attribute_deprecated void sws_shiftVec(SwsVector *a, int shift)
Definition: utils.c:2196