FFmpeg  4.3
imgutils.h
Go to the documentation of this file.
1 /*
2  * This file is part of FFmpeg.
3  *
4  * FFmpeg is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2.1 of the License, or (at your option) any later version.
8  *
9  * FFmpeg is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with FFmpeg; if not, write to the Free Software
16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17  */
18 
19 #ifndef AVUTIL_IMGUTILS_H
20 #define AVUTIL_IMGUTILS_H
21 
22 /**
23  * @file
24  * misc image utilities
25  *
26  * @addtogroup lavu_picture
27  * @{
28  */
29 
30 #include "avutil.h"
31 #include "pixdesc.h"
32 #include "rational.h"
33 
34 /**
35  * Compute the max pixel step for each plane of an image with a
36  * format described by pixdesc.
37  *
38  * The pixel step is the distance in bytes between the first byte of
39  * the group of bytes which describe a pixel component and the first
40  * byte of the successive group in the same plane for the same
41  * component.
42  *
43  * @param max_pixsteps an array which is filled with the max pixel step
44  * for each plane. Since a plane may contain different pixel
45  * components, the computed max_pixsteps[plane] is relative to the
46  * component in the plane with the max pixel step.
47  * @param max_pixstep_comps an array which is filled with the component
48  * for each plane which has the max pixel step. May be NULL.
49  */
50 void av_image_fill_max_pixsteps(int max_pixsteps[4], int max_pixstep_comps[4],
51  const AVPixFmtDescriptor *pixdesc);
52 
53 /**
54  * Compute the size of an image line with format pix_fmt and width
55  * width for the plane plane.
56  *
57  * @return the computed size in bytes
58  */
59 int av_image_get_linesize(enum AVPixelFormat pix_fmt, int width, int plane);
60 
61 /**
62  * Fill plane linesizes for an image with pixel format pix_fmt and
63  * width width.
64  *
65  * @param linesizes array to be filled with the linesize for each plane
66  * @return >= 0 in case of success, a negative error code otherwise
67  */
68 int av_image_fill_linesizes(int linesizes[4], enum AVPixelFormat pix_fmt, int width);
69 
70 /**
71  * Fill plane data pointers for an image with pixel format pix_fmt and
72  * height height.
73  *
74  * @param data pointers array to be filled with the pointer for each image plane
75  * @param ptr the pointer to a buffer which will contain the image
76  * @param linesizes the array containing the linesize for each
77  * plane, should be filled by av_image_fill_linesizes()
78  * @return the size in bytes required for the image buffer, a negative
79  * error code in case of failure
80  */
82  uint8_t *ptr, const int linesizes[4]);
83 
84 /**
85  * Allocate an image with size w and h and pixel format pix_fmt, and
86  * fill pointers and linesizes accordingly.
87  * The allocated image buffer has to be freed by using
88  * av_freep(&pointers[0]).
89  *
90  * @param align the value to use for buffer size alignment
91  * @return the size in bytes required for the image buffer, a negative
92  * error code in case of failure
93  */
94 int av_image_alloc(uint8_t *pointers[4], int linesizes[4],
95  int w, int h, enum AVPixelFormat pix_fmt, int align);
96 
97 /**
98  * Copy image plane from src to dst.
99  * That is, copy "height" number of lines of "bytewidth" bytes each.
100  * The first byte of each successive line is separated by *_linesize
101  * bytes.
102  *
103  * bytewidth must be contained by both absolute values of dst_linesize
104  * and src_linesize, otherwise the function behavior is undefined.
105  *
106  * @param dst_linesize linesize for the image plane in dst
107  * @param src_linesize linesize for the image plane in src
108  */
109 void av_image_copy_plane(uint8_t *dst, int dst_linesize,
110  const uint8_t *src, int src_linesize,
111  int bytewidth, int height);
112 
113 /**
114  * Copy image in src_data to dst_data.
115  *
116  * @param dst_linesizes linesizes for the image in dst_data
117  * @param src_linesizes linesizes for the image in src_data
118  */
119 void av_image_copy(uint8_t *dst_data[4], int dst_linesizes[4],
120  const uint8_t *src_data[4], const int src_linesizes[4],
121  enum AVPixelFormat pix_fmt, int width, int height);
122 
123 /**
124  * Copy image data located in uncacheable (e.g. GPU mapped) memory. Where
125  * available, this function will use special functionality for reading from such
126  * memory, which may result in greatly improved performance compared to plain
127  * av_image_copy().
128  *
129  * The data pointers and the linesizes must be aligned to the maximum required
130  * by the CPU architecture.
131  *
132  * @note The linesize parameters have the type ptrdiff_t here, while they are
133  * int for av_image_copy().
134  * @note On x86, the linesizes currently need to be aligned to the cacheline
135  * size (i.e. 64) to get improved performance.
136  */
137 void av_image_copy_uc_from(uint8_t *dst_data[4], const ptrdiff_t dst_linesizes[4],
138  const uint8_t *src_data[4], const ptrdiff_t src_linesizes[4],
139  enum AVPixelFormat pix_fmt, int width, int height);
140 
141 /**
142  * Setup the data pointers and linesizes based on the specified image
143  * parameters and the provided array.
144  *
145  * The fields of the given image are filled in by using the src
146  * address which points to the image data buffer. Depending on the
147  * specified pixel format, one or multiple image data pointers and
148  * line sizes will be set. If a planar format is specified, several
149  * pointers will be set pointing to the different picture planes and
150  * the line sizes of the different planes will be stored in the
151  * lines_sizes array. Call with src == NULL to get the required
152  * size for the src buffer.
153  *
154  * To allocate the buffer and fill in the dst_data and dst_linesize in
155  * one call, use av_image_alloc().
156  *
157  * @param dst_data data pointers to be filled in
158  * @param dst_linesize linesizes for the image in dst_data to be filled in
159  * @param src buffer which will contain or contains the actual image data, can be NULL
160  * @param pix_fmt the pixel format of the image
161  * @param width the width of the image in pixels
162  * @param height the height of the image in pixels
163  * @param align the value used in src for linesize alignment
164  * @return the size in bytes required for src, a negative error code
165  * in case of failure
166  */
167 int av_image_fill_arrays(uint8_t *dst_data[4], int dst_linesize[4],
168  const uint8_t *src,
169  enum AVPixelFormat pix_fmt, int width, int height, int align);
170 
171 /**
172  * Return the size in bytes of the amount of data required to store an
173  * image with the given parameters.
174  *
175  * @param pix_fmt the pixel format of the image
176  * @param width the width of the image in pixels
177  * @param height the height of the image in pixels
178  * @param align the assumed linesize alignment
179  * @return the buffer size in bytes, a negative error code in case of failure
180  */
181 int av_image_get_buffer_size(enum AVPixelFormat pix_fmt, int width, int height, int align);
182 
183 /**
184  * Copy image data from an image into a buffer.
185  *
186  * av_image_get_buffer_size() can be used to compute the required size
187  * for the buffer to fill.
188  *
189  * @param dst a buffer into which picture data will be copied
190  * @param dst_size the size in bytes of dst
191  * @param src_data pointers containing the source image data
192  * @param src_linesize linesizes for the image in src_data
193  * @param pix_fmt the pixel format of the source image
194  * @param width the width of the source image in pixels
195  * @param height the height of the source image in pixels
196  * @param align the assumed linesize alignment for dst
197  * @return the number of bytes written to dst, or a negative value
198  * (error code) on error
199  */
200 int av_image_copy_to_buffer(uint8_t *dst, int dst_size,
201  const uint8_t * const src_data[4], const int src_linesize[4],
202  enum AVPixelFormat pix_fmt, int width, int height, int align);
203 
204 /**
205  * Check if the given dimension of an image is valid, meaning that all
206  * bytes of the image can be addressed with a signed int.
207  *
208  * @param w the width of the picture
209  * @param h the height of the picture
210  * @param log_offset the offset to sum to the log level for logging with log_ctx
211  * @param log_ctx the parent logging context, it may be NULL
212  * @return >= 0 if valid, a negative error code otherwise
213  */
214 int av_image_check_size(unsigned int w, unsigned int h, int log_offset, void *log_ctx);
215 
216 /**
217  * Check if the given dimension of an image is valid, meaning that all
218  * bytes of a plane of an image with the specified pix_fmt can be addressed
219  * with a signed int.
220  *
221  * @param w the width of the picture
222  * @param h the height of the picture
223  * @param max_pixels the maximum number of pixels the user wants to accept
224  * @param pix_fmt the pixel format, can be AV_PIX_FMT_NONE if unknown.
225  * @param log_offset the offset to sum to the log level for logging with log_ctx
226  * @param log_ctx the parent logging context, it may be NULL
227  * @return >= 0 if valid, a negative error code otherwise
228  */
229 int av_image_check_size2(unsigned int w, unsigned int h, int64_t max_pixels, enum AVPixelFormat pix_fmt, int log_offset, void *log_ctx);
230 
231 /**
232  * Check if the given sample aspect ratio of an image is valid.
233  *
234  * It is considered invalid if the denominator is 0 or if applying the ratio
235  * to the image size would make the smaller dimension less than 1. If the
236  * sar numerator is 0, it is considered unknown and will return as valid.
237  *
238  * @param w width of the image
239  * @param h height of the image
240  * @param sar sample aspect ratio of the image
241  * @return 0 if valid, a negative AVERROR code otherwise
242  */
243 int av_image_check_sar(unsigned int w, unsigned int h, AVRational sar);
244 
245 /**
246  * Overwrite the image data with black. This is suitable for filling a
247  * sub-rectangle of an image, meaning the padding between the right most pixel
248  * and the left most pixel on the next line will not be overwritten. For some
249  * formats, the image size might be rounded up due to inherent alignment.
250  *
251  * If the pixel format has alpha, the alpha is cleared to opaque.
252  *
253  * This can return an error if the pixel format is not supported. Normally, all
254  * non-hwaccel pixel formats should be supported.
255  *
256  * Passing NULL for dst_data is allowed. Then the function returns whether the
257  * operation would have succeeded. (It can return an error if the pix_fmt is
258  * not supported.)
259  *
260  * @param dst_data data pointers to destination image
261  * @param dst_linesize linesizes for the destination image
262  * @param pix_fmt the pixel format of the image
263  * @param range the color range of the image (important for colorspaces such as YUV)
264  * @param width the width of the image in pixels
265  * @param height the height of the image in pixels
266  * @return 0 if the image data was cleared, a negative AVERROR code otherwise
267  */
268 int av_image_fill_black(uint8_t *dst_data[4], const ptrdiff_t dst_linesize[4],
269  enum AVPixelFormat pix_fmt, enum AVColorRange range,
270  int width, int height);
271 
272 /**
273  * @}
274  */
275 
276 
277 #endif /* AVUTIL_IMGUTILS_H */
AVPixelFormat
AVPixelFormat
Pixel format.
Definition: pixfmt.h:64
rational.h
pixdesc.h
data
const char data[16]
Definition: mxf.c:91
av_image_copy_plane
void av_image_copy_plane(uint8_t *dst, int dst_linesize, const uint8_t *src, int src_linesize, int bytewidth, int height)
Copy image plane from src to dst.
Definition: imgutils.c:338
av_image_fill_pointers
int av_image_fill_pointers(uint8_t *data[4], enum AVPixelFormat pix_fmt, int height, uint8_t *ptr, const int linesizes[4])
Fill plane data pointers for an image with pixel format pix_fmt and height height.
Definition: imgutils.c:111
av_image_check_size2
int av_image_check_size2(unsigned int w, unsigned int h, int64_t max_pixels, enum AVPixelFormat pix_fmt, int log_offset, void *log_ctx)
Check if the given dimension of an image is valid, meaning that all bytes of a plane of an image with...
Definition: imgutils.c:253
width
#define width
av_image_fill_linesizes
int av_image_fill_linesizes(int linesizes[4], enum AVPixelFormat pix_fmt, int width)
Fill plane linesizes for an image with pixel format pix_fmt and width width.
Definition: imgutils.c:89
pointers
Undefined Behavior In the C some operations are like signed integer dereferencing freed pointers
Definition: undefined.txt:4
pix_fmt
static enum AVPixelFormat pix_fmt
Definition: demuxing_decoding.c:40
AVRational
Rational number (pair of numerator and denominator).
Definition: rational.h:58
src
#define src
Definition: vp8dsp.c:254
av_image_fill_black
int av_image_fill_black(uint8_t *dst_data[4], const ptrdiff_t dst_linesize[4], enum AVPixelFormat pix_fmt, enum AVColorRange range, int width, int height)
Overwrite the image data with black.
Definition: imgutils.c:534
av_image_alloc
int av_image_alloc(uint8_t *pointers[4], int linesizes[4], int w, int h, enum AVPixelFormat pix_fmt, int align)
Allocate an image with size w and h and pixel format pix_fmt, and fill pointers and linesizes accordi...
Definition: imgutils.c:192
av_image_fill_arrays
int av_image_fill_arrays(uint8_t *dst_data[4], int dst_linesize[4], const uint8_t *src, enum AVPixelFormat pix_fmt, int width, int height, int align)
Setup the data pointers and linesizes based on the specified image parameters and the provided array.
Definition: imgutils.c:411
height
#define height
av_image_get_buffer_size
int av_image_get_buffer_size(enum AVPixelFormat pix_fmt, int width, int height, int align)
Return the size in bytes of the amount of data required to store an image with the given parameters.
Definition: imgutils.c:431
av_image_get_linesize
int av_image_get_linesize(enum AVPixelFormat pix_fmt, int width, int plane)
Compute the size of an image line with format pix_fmt and width width for the plane plane.
Definition: imgutils.c:76
av_image_copy_uc_from
void av_image_copy_uc_from(uint8_t *dst_data[4], const ptrdiff_t dst_linesizes[4], const uint8_t *src_data[4], const ptrdiff_t src_linesizes[4], enum AVPixelFormat pix_fmt, int width, int height)
Copy image data located in uncacheable (e.g.
Definition: imgutils.c:403
uint8_t
uint8_t
Definition: audio_convert.c:194
w
FFmpeg Automated Testing Environment ************************************Introduction Using FATE from your FFmpeg source directory Submitting the results to the FFmpeg result aggregation server Uploading new samples to the fate suite FATE makefile targets and variables Makefile targets Makefile variables Examples Introduction **************FATE is an extended regression suite on the client side and a means for results aggregation and presentation on the server side The first part of this document explains how you can use FATE from your FFmpeg source directory to test your ffmpeg binary The second part describes how you can run FATE to submit the results to FFmpeg’s FATE server In any way you can have a look at the publicly viewable FATE results by visiting this as it can be seen if some test on some platform broke with their recent contribution This usually happens on the platforms the developers could not test on The second part of this document describes how you can run FATE to submit your results to FFmpeg’s FATE server If you want to submit your results be sure to check that your combination of OS and compiler is not already listed on the above mentioned website In the third part you can find a comprehensive listing of FATE makefile targets and variables Using FATE from your FFmpeg source directory **********************************************If you want to run FATE on your machine you need to have the samples in place You can get the samples via the build target fate rsync Use this command from the top level source this will cause FATE to fail NOTE To use a custom wrapper to run the pass ‘ target exec’ to ‘configure’ or set the TARGET_EXEC Make variable Submitting the results to the FFmpeg result aggregation server ****************************************************************To submit your results to the server you should run fate through the shell script ‘tests fate sh’ from the FFmpeg sources This script needs to be invoked with a configuration file as its first argument tests fate sh path to fate_config A configuration file template with comments describing the individual configuration variables can be found at ‘doc fate_config sh template’ Create a configuration that suits your based on the configuration template The ‘slot’ configuration variable can be any string that is not yet but it is suggested that you name it adhering to the following pattern ‘ARCH OS COMPILER COMPILER VERSION’ The configuration file itself will be sourced in a shell therefore all shell features may be used This enables you to setup the environment as you need it for your build For your first test runs the ‘fate_recv’ variable should be empty or commented out This will run everything as normal except that it will omit the submission of the results to the server The following files should be present in $workdir as specified in the configuration it may help to try out the ‘ssh’ command with one or more ‘ v’ options You should get detailed output concerning your SSH configuration and the authentication process The only thing left is to automate the execution of the fate sh script and the synchronisation of the samples directory Uploading new samples to the fate suite *****************************************If you need a sample uploaded send a mail to samples request This is for developers who have an account on the fate suite server If you upload new please make sure they are as small as space on each network bandwidth and so on benefit from smaller test cases Also keep in mind older checkouts use existing sample that means in practice generally do not remove or overwrite files as it likely would break older checkouts or releases Also all needed samples for a commit should be ideally before the push If you need an account for frequently uploading samples or you wish to help others by doing that send a mail to ffmpeg devel rsync vauL Duo ug o o w
Definition: fate.txt:150
av_image_copy
void av_image_copy(uint8_t *dst_data[4], int dst_linesizes[4], const uint8_t *src_data[4], const int src_linesizes[4], enum AVPixelFormat pix_fmt, int width, int height)
Copy image in src_data to dst_data.
Definition: imgutils.c:387
av_image_fill_max_pixsteps
void av_image_fill_max_pixsteps(int max_pixsteps[4], int max_pixstep_comps[4], const AVPixFmtDescriptor *pixdesc)
Compute the max pixel step for each plane of an image with a format described by pixdesc.
Definition: imgutils.c:35
avutil.h
AVPixFmtDescriptor
Descriptor that unambiguously describes how the bits of a pixel are stored in the up to 4 data planes...
Definition: pixdesc.h:81
av_image_copy_to_buffer
int av_image_copy_to_buffer(uint8_t *dst, int dst_size, const uint8_t *const src_data[4], const int src_linesize[4], enum AVPixelFormat pix_fmt, int width, int height, int align)
Copy image data from an image into a buffer.
Definition: imgutils.c:453
h
h
Definition: vp9dsp_template.c:2038
av_image_check_sar
int av_image_check_sar(unsigned int w, unsigned int h, AVRational sar)
Check if the given sample aspect ratio of an image is valid.
Definition: imgutils.c:287
av_image_check_size
int av_image_check_size(unsigned int w, unsigned int h, int log_offset, void *log_ctx)
Check if the given dimension of an image is valid, meaning that all bytes of the image can be address...
Definition: imgutils.c:282
AVColorRange
AVColorRange
MPEG vs JPEG YUV range.
Definition: pixfmt.h:532