swscale.h 11.7 KB
Newer Older
1
/*
2
 * Copyright (C) 2001-2011 Michael Niedermayer <michaelni@gmx.at>
3 4 5
 *
 * This file is part of FFmpeg.
 *
6 7 8 9
 * 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.
10 11 12
 *
 * FFmpeg is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 14
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
15
 *
16 17
 * You should have received a copy of the GNU Lesser General Public
 * 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
 */
Arpi's avatar
Arpi committed
20

21 22
#ifndef SWSCALE_SWSCALE_H
#define SWSCALE_SWSCALE_H
23

24
/**
25
 * @file
26
 * @ingroup libsws
27 28 29
 * external API header
 */

30 31
#include <stdint.h>

32
#include "libavutil/avutil.h"
33
#include "libavutil/log.h"
34
#include "libavutil/pixfmt.h"
35
#include "version.h"
36

37
/**
38 39 40
 * @defgroup libsws libswscale
 * Color conversion and scaling library.
 *
41 42
 * @{
 *
43
 * Return the LIBSWSCALE_VERSION_INT constant.
44 45 46
 */
unsigned swscale_version(void);

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 59 60 61 62 63 64 65 66 67 68
#define SWS_FAST_BILINEAR     1
#define SWS_BILINEAR          2
#define SWS_BICUBIC           4
#define SWS_X                 8
#define SWS_POINT          0x10
#define SWS_AREA           0x20
#define SWS_BICUBLIN       0x40
#define SWS_GAUSS          0x80
#define SWS_SINC          0x100
#define SWS_LANCZOS       0x200
#define SWS_SPLINE        0x400
69

70 71
#define SWS_SRC_V_CHR_DROP_MASK     0x30000
#define SWS_SRC_V_CHR_DROP_SHIFT    16
72

73
#define SWS_PARAM_DEFAULT           123456
Michael Niedermayer's avatar
Michael Niedermayer committed
74

75
#define SWS_PRINT_INFO              0x1000
Michael Niedermayer's avatar
Michael Niedermayer committed
76

Diego Biurrun's avatar
Diego Biurrun committed
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 82 83
#define SWS_FULL_CHR_H_INP    0x4000
#define SWS_DIRECT_BGR        0x8000
#define SWS_ACCURATE_RND      0x40000
Michael Niedermayer's avatar
Michael Niedermayer committed
84
#define SWS_BITEXACT          0x80000
85
#define SWS_ERROR_DIFFUSION  0x800000
86

87
#define SWS_MAX_REDUCE_CUTOFF 0.002
88

89 90 91 92 93 94 95
#define SWS_CS_ITU709         1
#define SWS_CS_FCC            4
#define SWS_CS_ITU601         5
#define SWS_CS_ITU624         5
#define SWS_CS_SMPTE170M      5
#define SWS_CS_SMPTE240M      7
#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 101 102 103
 * suitable for sws_setColorspaceDetails().
 *
 * @param colorspace One of the SWS_CS_* macros. If invalid,
 * SWS_CS_DEFAULT is used.
104
 */
105
const int *sws_getCoefficients(int colorspace);
Michael Niedermayer's avatar
Michael Niedermayer committed
106

107 108
// when used for filters they must have an odd number of elements
// coeffs cannot be shared between vectors
109
typedef struct SwsVector {
110 111
    double *coeff;              ///< pointer to the list of coefficients
    int length;                 ///< number of coefficients in the vector
112 113 114
} SwsVector;

// vectors can be shared
115
typedef struct SwsFilter {
116 117 118 119
    SwsVector *lumH;
    SwsVector *lumV;
    SwsVector *chrH;
    SwsVector *chrV;
120 121
} SwsFilter;

122
struct SwsContext;
123

124
/**
125
 * Return a positive value if pix_fmt is a supported input format, 0
126 127
 * otherwise.
 */
128
int sws_isSupportedInput(enum AVPixelFormat pix_fmt);
129 130

/**
131
 * Return a positive value if pix_fmt is a supported output format, 0
132 133
 * otherwise.
 */
134
int sws_isSupportedOutput(enum AVPixelFormat pix_fmt);
135

136 137 138 139 140 141 142
/**
 * @param[in]  pix_fmt the pixel format
 * @return a positive value if an endianness conversion for pix_fmt is
 * supported, 0 otherwise.
 */
int sws_isSupportedEndiannessConversion(enum AVPixelFormat pix_fmt);

143
/**
144
 * Allocate an empty SwsContext. This must be filled and passed to
Ramiro Polla's avatar
Ramiro Polla committed
145 146
 * sws_init_context(). For filling see AVOptions, options.c and
 * sws_setColorspaceDetails().
147 148 149 150
 */
struct SwsContext *sws_alloc_context(void);

/**
151
 * Initialize the swscaler context sws_context.
152 153 154
 *
 * @return zero or positive value on success, a negative value on
 * error
155
 */
156
av_warn_unused_result
157 158
int sws_init_context(struct SwsContext *sws_context, SwsFilter *srcFilter, SwsFilter *dstFilter);

159
/**
160
 * Free the swscaler context swsContext.
Stefano Sabatini's avatar
Stefano Sabatini committed
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 168 169 170 171 172 173 174 175
 * scaling/conversion operations using sws_scale().
 *
 * @param srcW the width of the source image
 * @param srcH the height of the source image
 * @param srcFormat the source image format
 * @param dstW the width of the destination image
 * @param dstH the height of the destination image
 * @param dstFormat the destination image format
 * @param flags specify which algorithm and options to use for rescaling
176 177 178 179 180 181
 * @param param extra parameters to tune the used scaler
 *              For SWS_BICUBIC param[0] and [1] tune the shape of the basis
 *              function, param[0] tunes f(1) and param[1] f´(1)
 *              For SWS_GAUSS param[0] tunes the exponent and thus cutoff
 *              frequency
 *              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 184
 * @note this function is to be removed after a saner alternative is
 *       written
185
 */
186 187
struct SwsContext *sws_getContext(int srcW, int srcH, enum AVPixelFormat srcFormat,
                                  int dstW, int dstH, enum AVPixelFormat dstFormat,
188
                                  int flags, SwsFilter *srcFilter,
189
                                  SwsFilter *dstFilter, const double *param);
Stefano Sabatini's avatar
Stefano Sabatini committed
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 195 196 197 198
 * rows in an image.
 *
 * Slices have to be provided in sequential order, either in
 * top-bottom or bottom-top order. If slices are provided in
 * non-sequential order the behavior of the function is undefined.
Stefano Sabatini's avatar
Stefano Sabatini committed
199
 *
200
 * @param c         the scaling context previously created with
Stefano Sabatini's avatar
Stefano Sabatini committed
201
 *                  sws_getContext()
202
 * @param srcSlice  the array containing the pointers to the planes of
Stefano Sabatini's avatar
Stefano Sabatini committed
203 204 205 206 207 208 209 210 211 212 213 214 215 216
 *                  the source slice
 * @param srcStride the array containing the strides for each plane of
 *                  the source image
 * @param srcSliceY the position in the source image of the slice to
 *                  process, that is the number (counted starting from
 *                  zero) in the image of the first row of the slice
 * @param srcSliceH the height of the source slice, that is the number
 *                  of rows in the slice
 * @param dst       the array containing the pointers to the planes of
 *                  the destination image
 * @param dstStride the array containing the strides for each plane of
 *                  the destination image
 * @return          the height of the output slice
 */
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 223 224 225 226 227 228
 * @param dstRange flag indicating the while-black range of the output (1=jpeg / 0=mpeg)
 * @param srcRange flag indicating the while-black range of the input (1=jpeg / 0=mpeg)
 * @param table the yuv2rgb coefficients describing the output yuv space, normally ff_yuv2rgb_coeffs[x]
 * @param inv_table the yuv2rgb coefficients describing the input yuv space, normally ff_yuv2rgb_coeffs[x]
 * @param brightness 16.16 fixed point brightness correction
 * @param contrast 16.16 fixed point contrast correction
 * @param saturation 16.16 fixed point saturation correction
229 230
 * @return -1 if not supported
 */
231 232 233
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);
234 235 236 237

/**
 * @return -1 if not supported
 */
238 239 240
int sws_getColorspaceDetails(struct SwsContext *c, int **inv_table,
                             int *srcRange, int **table, int *dstRange,
                             int *brightness, int *contrast, int *saturation);
241

242
/**
243
 * Allocate and return an uninitialized vector with length coefficients.
244 245 246
 */
SwsVector *sws_allocVec(int length);

247
/**
248 249
 * Return a normalized Gaussian curve used to filter stuff
 * 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 264 265 266 267 268 269 270 271 272
#if FF_API_SWS_VECTOR
attribute_deprecated SwsVector *sws_getConstVec(double c, int length);
attribute_deprecated SwsVector *sws_getIdentityVec(void);
attribute_deprecated void sws_convVec(SwsVector *a, SwsVector *b);
attribute_deprecated void sws_addVec(SwsVector *a, SwsVector *b);
attribute_deprecated void sws_subVec(SwsVector *a, SwsVector *b);
attribute_deprecated void sws_shiftVec(SwsVector *a, int shift);
attribute_deprecated SwsVector *sws_cloneVec(SwsVector *a);
attribute_deprecated void sws_printVec2(SwsVector *a, AVClass *log_ctx, int log_level);
#endif
273

274 275
void sws_freeVec(SwsVector *a);

276
SwsFilter *sws_getDefaultFilter(float lumaGBlur, float chromaGBlur,
277
                                float lumaSharpen, float chromaSharpen,
278 279
                                float chromaHShift, float chromaVShift,
                                int verbose);
280 281
void sws_freeFilter(SwsFilter *filter);

282
/**
283
 * Check if context can be reused, otherwise reallocate a new one.
284
 *
Stefano Sabatini's avatar
Stefano Sabatini committed
285 286 287 288
 * If context is NULL, just calls sws_getContext() to get a new
 * context. Otherwise, checks if the parameters are the ones already
 * saved in context. If that is the case, returns the current
 * context. Otherwise, frees context and gets a new context with
289 290
 * the new parameters.
 *
291
 * Be warned that srcFilter and dstFilter are not checked, they
292
 * are assumed to remain the same.
293
 */
294
struct SwsContext *sws_getCachedContext(struct SwsContext *context,
295 296
                                        int srcW, int srcH, enum AVPixelFormat srcFormat,
                                        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 304 305 306 307 308 309
 *
 * The output frame will have the same packed format as the palette.
 *
 * @param src        source frame buffer
 * @param dst        destination frame buffer
 * @param num_pixels number of pixels to convert
 * @param palette    array with [256] entries, which must match color arrangement (RGB or BGR) of src
 */
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 316 317 318 319 320 321
 *
 * With the palette format "ABCD", the destination frame ends up with the format "ABC".
 *
 * @param src        source frame buffer
 * @param dst        destination frame buffer
 * @param num_pixels number of pixels to convert
 * @param palette    array with [256] entries, which must match color arrangement (RGB or BGR) of src
 */
322
void sws_convertPalette8ToPacked24(const uint8_t *src, uint8_t *dst, int num_pixels, const uint8_t *palette);
323

324 325 326 327 328 329 330
/**
 * Get the AVClass for swsContext. It can be used in combination with
 * AV_OPT_SEARCH_FAKE_OBJ for examining options.
 *
 * @see av_opt_find().
 */
const AVClass *sws_get_class(void);
331

332 333 334 335
/**
 * @}
 */

336
#endif /* SWSCALE_SWSCALE_H */