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/frame.h" |
34 | #include "libavutil/log.h" |
35 | #include "libavutil/pixfmt.h" |
36 | #include "version_major.h" |
37 | #ifndef HAVE_AV_CONFIG_H |
38 | /* When included as part of the ffmpeg build, only include the major version |
39 | * to avoid unnecessary rebuilds. When included externally, keep including |
40 | * the full version information. */ |
41 | #include "version.h" |
42 | #endif |
43 | |
44 | /** |
45 | * @defgroup libsws libswscale |
46 | * Color conversion and scaling library. |
47 | * |
48 | * @{ |
49 | * |
50 | * Return the LIBSWSCALE_VERSION_INT constant. |
51 | */ |
52 | unsigned swscale_version(void); |
53 | |
54 | /** |
55 | * Return the libswscale build-time configuration. |
56 | */ |
57 | const char *swscale_configuration(void); |
58 | |
59 | /** |
60 | * Return the libswscale license. |
61 | */ |
62 | const char *swscale_license(void); |
63 | |
64 | /* values for the flags, the stuff on the command line is different */ |
65 | #define SWS_FAST_BILINEAR 1 |
66 | #define SWS_BILINEAR 2 |
67 | #define SWS_BICUBIC 4 |
68 | #define SWS_X 8 |
69 | #define SWS_POINT 0x10 |
70 | #define SWS_AREA 0x20 |
71 | #define SWS_BICUBLIN 0x40 |
72 | #define SWS_GAUSS 0x80 |
73 | #define SWS_SINC 0x100 |
74 | #define SWS_LANCZOS 0x200 |
75 | #define SWS_SPLINE 0x400 |
76 | |
77 | #define SWS_SRC_V_CHR_DROP_MASK 0x30000 |
78 | #define SWS_SRC_V_CHR_DROP_SHIFT 16 |
79 | |
80 | #define SWS_PARAM_DEFAULT 123456 |
81 | |
82 | #define SWS_PRINT_INFO 0x1000 |
83 | |
84 | //the following 3 flags are not completely implemented |
85 | //internal chrominance subsampling info |
86 | #define SWS_FULL_CHR_H_INT 0x2000 |
87 | //input subsampling info |
88 | #define SWS_FULL_CHR_H_INP 0x4000 |
89 | #define SWS_DIRECT_BGR 0x8000 |
90 | #define SWS_ACCURATE_RND 0x40000 |
91 | #define SWS_BITEXACT 0x80000 |
92 | #define SWS_ERROR_DIFFUSION 0x800000 |
93 | |
94 | #define SWS_MAX_REDUCE_CUTOFF 0.002 |
95 | |
96 | #define SWS_CS_ITU709 1 |
97 | #define SWS_CS_FCC 4 |
98 | #define SWS_CS_ITU601 5 |
99 | #define SWS_CS_ITU624 5 |
100 | #define SWS_CS_SMPTE170M 5 |
101 | #define SWS_CS_SMPTE240M 7 |
102 | #define SWS_CS_DEFAULT 5 |
103 | #define SWS_CS_BT2020 9 |
104 | |
105 | /** |
106 | * Return a pointer to yuv<->rgb coefficients for the given colorspace |
107 | * suitable for sws_setColorspaceDetails(). |
108 | * |
109 | * @param colorspace One of the SWS_CS_* macros. If invalid, |
110 | * SWS_CS_DEFAULT is used. |
111 | */ |
112 | const int *sws_getCoefficients(int colorspace); |
113 | |
114 | // when used for filters they must have an odd number of elements |
115 | // coeffs cannot be shared between vectors |
116 | typedef struct SwsVector { |
117 | double *coeff; ///< pointer to the list of coefficients |
118 | int length; ///< number of coefficients in the vector |
119 | } SwsVector; |
120 | |
121 | // vectors can be shared |
122 | typedef struct SwsFilter { |
123 | SwsVector *lumH; |
124 | SwsVector *lumV; |
125 | SwsVector *chrH; |
126 | SwsVector *chrV; |
127 | } SwsFilter; |
128 | |
129 | struct SwsContext; |
130 | |
131 | /** |
132 | * Return a positive value if pix_fmt is a supported input format, 0 |
133 | * otherwise. |
134 | */ |
135 | int sws_isSupportedInput(enum AVPixelFormat pix_fmt); |
136 | |
137 | /** |
138 | * Return a positive value if pix_fmt is a supported output format, 0 |
139 | * otherwise. |
140 | */ |
141 | int sws_isSupportedOutput(enum AVPixelFormat pix_fmt); |
142 | |
143 | /** |
144 | * @param[in] pix_fmt the pixel format |
145 | * @return a positive value if an endianness conversion for pix_fmt is |
146 | * supported, 0 otherwise. |
147 | */ |
148 | int sws_isSupportedEndiannessConversion(enum AVPixelFormat pix_fmt); |
149 | |
150 | /** |
151 | * Allocate an empty SwsContext. This must be filled and passed to |
152 | * sws_init_context(). For filling see AVOptions, options.c and |
153 | * sws_setColorspaceDetails(). |
154 | */ |
155 | struct SwsContext *sws_alloc_context(void); |
156 | |
157 | /** |
158 | * Initialize the swscaler context sws_context. |
159 | * |
160 | * @return zero or positive value on success, a negative value on |
161 | * error |
162 | */ |
163 | av_warn_unused_result |
164 | int sws_init_context(struct SwsContext *sws_context, SwsFilter *srcFilter, SwsFilter *dstFilter); |
165 | |
166 | /** |
167 | * Free the swscaler context swsContext. |
168 | * If swsContext is NULL, then does nothing. |
169 | */ |
170 | void sws_freeContext(struct SwsContext *swsContext); |
171 | |
172 | /** |
173 | * Allocate and return an SwsContext. You need it to perform |
174 | * scaling/conversion operations using sws_scale(). |
175 | * |
176 | * @param srcW the width of the source image |
177 | * @param srcH the height of the source image |
178 | * @param srcFormat the source image format |
179 | * @param dstW the width of the destination image |
180 | * @param dstH the height of the destination image |
181 | * @param dstFormat the destination image format |
182 | * @param flags specify which algorithm and options to use for rescaling |
183 | * @param param extra parameters to tune the used scaler |
184 | * For SWS_BICUBIC param[0] and [1] tune the shape of the basis |
185 | * function, param[0] tunes f(1) and param[1] f´(1) |
186 | * For SWS_GAUSS param[0] tunes the exponent and thus cutoff |
187 | * frequency |
188 | * For SWS_LANCZOS param[0] tunes the width of the window function |
189 | * @return a pointer to an allocated context, or NULL in case of error |
190 | * @note this function is to be removed after a saner alternative is |
191 | * written |
192 | */ |
193 | struct SwsContext *sws_getContext(int srcW, int srcH, enum AVPixelFormat srcFormat, |
194 | int dstW, int dstH, enum AVPixelFormat dstFormat, |
195 | int flags, SwsFilter *srcFilter, |
196 | SwsFilter *dstFilter, const double *param); |
197 | |
198 | /** |
199 | * Scale the image slice in srcSlice and put the resulting scaled |
200 | * slice in the image in dst. A slice is a sequence of consecutive |
201 | * rows in an image. |
202 | * |
203 | * Slices have to be provided in sequential order, either in |
204 | * top-bottom or bottom-top order. If slices are provided in |
205 | * non-sequential order the behavior of the function is undefined. |
206 | * |
207 | * @param c the scaling context previously created with |
208 | * sws_getContext() |
209 | * @param srcSlice the array containing the pointers to the planes of |
210 | * the source slice |
211 | * @param srcStride the array containing the strides for each plane of |
212 | * the source image |
213 | * @param srcSliceY the position in the source image of the slice to |
214 | * process, that is the number (counted starting from |
215 | * zero) in the image of the first row of the slice |
216 | * @param srcSliceH the height of the source slice, that is the number |
217 | * of rows in the slice |
218 | * @param dst the array containing the pointers to the planes of |
219 | * the destination image |
220 | * @param dstStride the array containing the strides for each plane of |
221 | * the destination image |
222 | * @return the height of the output slice |
223 | */ |
224 | int sws_scale(struct SwsContext *c, const uint8_t *const srcSlice[], |
225 | const int srcStride[], int srcSliceY, int srcSliceH, |
226 | uint8_t *const dst[], const int dstStride[]); |
227 | |
228 | /** |
229 | * Scale source data from src and write the output to dst. |
230 | * |
231 | * This is merely a convenience wrapper around |
232 | * - sws_frame_start() |
233 | * - sws_send_slice(0, src->height) |
234 | * - sws_receive_slice(0, dst->height) |
235 | * - sws_frame_end() |
236 | * |
237 | * @param c The scaling context |
238 | * @param dst The destination frame. See documentation for sws_frame_start() for |
239 | * more details. |
240 | * @param src The source frame. |
241 | * |
242 | * @return 0 on success, a negative AVERROR code on failure |
243 | */ |
244 | int sws_scale_frame(struct SwsContext *c, AVFrame *dst, const AVFrame *src); |
245 | |
246 | /** |
247 | * Initialize the scaling process for a given pair of source/destination frames. |
248 | * Must be called before any calls to sws_send_slice() and sws_receive_slice(). |
249 | * |
250 | * This function will retain references to src and dst, so they must both use |
251 | * refcounted buffers (if allocated by the caller, in case of dst). |
252 | * |
253 | * @param c The scaling context |
254 | * @param dst The destination frame. |
255 | * |
256 | * The data buffers may either be already allocated by the caller or |
257 | * left clear, in which case they will be allocated by the scaler. |
258 | * The latter may have performance advantages - e.g. in certain cases |
259 | * some output planes may be references to input planes, rather than |
260 | * copies. |
261 | * |
262 | * Output data will be written into this frame in successful |
263 | * sws_receive_slice() calls. |
264 | * @param src The source frame. The data buffers must be allocated, but the |
265 | * frame data does not have to be ready at this point. Data |
266 | * availability is then signalled by sws_send_slice(). |
267 | * @return 0 on success, a negative AVERROR code on failure |
268 | * |
269 | * @see sws_frame_end() |
270 | */ |
271 | int sws_frame_start(struct SwsContext *c, AVFrame *dst, const AVFrame *src); |
272 | |
273 | /** |
274 | * Finish the scaling process for a pair of source/destination frames previously |
275 | * submitted with sws_frame_start(). Must be called after all sws_send_slice() |
276 | * and sws_receive_slice() calls are done, before any new sws_frame_start() |
277 | * calls. |
278 | * |
279 | * @param c The scaling context |
280 | */ |
281 | void sws_frame_end(struct SwsContext *c); |
282 | |
283 | /** |
284 | * Indicate that a horizontal slice of input data is available in the source |
285 | * frame previously provided to sws_frame_start(). The slices may be provided in |
286 | * any order, but may not overlap. For vertically subsampled pixel formats, the |
287 | * slices must be aligned according to subsampling. |
288 | * |
289 | * @param c The scaling context |
290 | * @param slice_start first row of the slice |
291 | * @param slice_height number of rows in the slice |
292 | * |
293 | * @return a non-negative number on success, a negative AVERROR code on failure. |
294 | */ |
295 | int sws_send_slice(struct SwsContext *c, unsigned int slice_start, |
296 | unsigned int slice_height); |
297 | |
298 | /** |
299 | * Request a horizontal slice of the output data to be written into the frame |
300 | * previously provided to sws_frame_start(). |
301 | * |
302 | * @param c The scaling context |
303 | * @param slice_start first row of the slice; must be a multiple of |
304 | * sws_receive_slice_alignment() |
305 | * @param slice_height number of rows in the slice; must be a multiple of |
306 | * sws_receive_slice_alignment(), except for the last slice |
307 | * (i.e. when slice_start+slice_height is equal to output |
308 | * frame height) |
309 | * |
310 | * @return a non-negative number if the data was successfully written into the output |
311 | * AVERROR(EAGAIN) if more input data needs to be provided before the |
312 | * output can be produced |
313 | * another negative AVERROR code on other kinds of scaling failure |
314 | */ |
315 | int sws_receive_slice(struct SwsContext *c, unsigned int slice_start, |
316 | unsigned int slice_height); |
317 | |
318 | /** |
319 | * Get the alignment required for slices |
320 | * |
321 | * @param c The scaling context |
322 | * @return alignment required for output slices requested with sws_receive_slice(). |
323 | * Slice offsets and sizes passed to sws_receive_slice() must be |
324 | * multiples of the value returned from this function. |
325 | */ |
326 | unsigned int sws_receive_slice_alignment(const struct SwsContext *c); |
327 | |
328 | /** |
329 | * @param c the scaling context |
330 | * @param dstRange flag indicating the while-black range of the output (1=jpeg / 0=mpeg) |
331 | * @param srcRange flag indicating the while-black range of the input (1=jpeg / 0=mpeg) |
332 | * @param table the yuv2rgb coefficients describing the output yuv space, normally ff_yuv2rgb_coeffs[x] |
333 | * @param inv_table the yuv2rgb coefficients describing the input yuv space, normally ff_yuv2rgb_coeffs[x] |
334 | * @param brightness 16.16 fixed point brightness correction |
335 | * @param contrast 16.16 fixed point contrast correction |
336 | * @param saturation 16.16 fixed point saturation correction |
337 | * |
338 | * @return A negative error code on error, non negative otherwise. |
339 | * If `LIBSWSCALE_VERSION_MAJOR < 7`, returns -1 if not supported. |
340 | */ |
341 | int sws_setColorspaceDetails(struct SwsContext *c, const int inv_table[4], |
342 | int srcRange, const int table[4], int dstRange, |
343 | int brightness, int contrast, int saturation); |
344 | |
345 | /** |
346 | * @return A negative error code on error, non negative otherwise. |
347 | * If `LIBSWSCALE_VERSION_MAJOR < 7`, returns -1 if not supported. |
348 | */ |
349 | int sws_getColorspaceDetails(struct SwsContext *c, int **inv_table, |
350 | int *srcRange, int **table, int *dstRange, |
351 | int *brightness, int *contrast, int *saturation); |
352 | |
353 | /** |
354 | * Allocate and return an uninitialized vector with length coefficients. |
355 | */ |
356 | SwsVector *sws_allocVec(int length); |
357 | |
358 | /** |
359 | * Return a normalized Gaussian curve used to filter stuff |
360 | * quality = 3 is high quality, lower is lower quality. |
361 | */ |
362 | SwsVector *sws_getGaussianVec(double variance, double quality); |
363 | |
364 | /** |
365 | * Scale all the coefficients of a by the scalar value. |
366 | */ |
367 | void sws_scaleVec(SwsVector *a, double scalar); |
368 | |
369 | /** |
370 | * Scale all the coefficients of a so that their sum equals height. |
371 | */ |
372 | void sws_normalizeVec(SwsVector *a, double height); |
373 | |
374 | void sws_freeVec(SwsVector *a); |
375 | |
376 | SwsFilter *sws_getDefaultFilter(float lumaGBlur, float chromaGBlur, |
377 | float lumaSharpen, float chromaSharpen, |
378 | float chromaHShift, float chromaVShift, |
379 | int verbose); |
380 | void sws_freeFilter(SwsFilter *filter); |
381 | |
382 | /** |
383 | * Check if context can be reused, otherwise reallocate a new one. |
384 | * |
385 | * If context is NULL, just calls sws_getContext() to get a new |
386 | * context. Otherwise, checks if the parameters are the ones already |
387 | * saved in context. If that is the case, returns the current |
388 | * context. Otherwise, frees context and gets a new context with |
389 | * the new parameters. |
390 | * |
391 | * Be warned that srcFilter and dstFilter are not checked, they |
392 | * are assumed to remain the same. |
393 | */ |
394 | struct SwsContext *sws_getCachedContext(struct SwsContext *context, |
395 | int srcW, int srcH, enum AVPixelFormat srcFormat, |
396 | int dstW, int dstH, enum AVPixelFormat dstFormat, |
397 | int flags, SwsFilter *srcFilter, |
398 | SwsFilter *dstFilter, const double *param); |
399 | |
400 | /** |
401 | * Convert an 8-bit paletted frame into a frame with a color depth of 32 bits. |
402 | * |
403 | * The output frame will have the same packed format as the palette. |
404 | * |
405 | * @param src source frame buffer |
406 | * @param dst destination frame buffer |
407 | * @param num_pixels number of pixels to convert |
408 | * @param palette array with [256] entries, which must match color arrangement (RGB or BGR) of src |
409 | */ |
410 | void sws_convertPalette8ToPacked32(const uint8_t *src, uint8_t *dst, int num_pixels, const uint8_t *palette); |
411 | |
412 | /** |
413 | * Convert an 8-bit paletted frame into a frame with a color depth of 24 bits. |
414 | * |
415 | * With the palette format "ABCD", the destination frame ends up with the format "ABC". |
416 | * |
417 | * @param src source frame buffer |
418 | * @param dst destination frame buffer |
419 | * @param num_pixels number of pixels to convert |
420 | * @param palette array with [256] entries, which must match color arrangement (RGB or BGR) of src |
421 | */ |
422 | void sws_convertPalette8ToPacked24(const uint8_t *src, uint8_t *dst, int num_pixels, const uint8_t *palette); |
423 | |
424 | /** |
425 | * Get the AVClass for swsContext. It can be used in combination with |
426 | * AV_OPT_SEARCH_FAKE_OBJ for examining options. |
427 | * |
428 | * @see av_opt_find(). |
429 | */ |
430 | const AVClass *sws_get_class(void); |
431 | |
432 | /** |
433 | * @} |
434 | */ |
435 | |
436 | #endif /* SWSCALE_SWSCALE_H */ |
437 | |