\input texinfo @c -*- texinfo -*-@documentencoding UTF-8 @settitle Developer Documentation@titlepage@center @titlefont{Developer Documentation}@end titlepage @top @contents @chapter Introduction This text is concerned with the development @emph{of} FFmpeg itself. Informationon using the FFmpeg libraries in other programs can be found elsewhere, e.g. in:@itemize @bullet@itemthe installed header files@item@url{http://ffmpeg.org/doxygen/trunk/index.html, the Doxygen documentation}generated from the headers@itemthe examples under @file{doc/examples}@end itemize For more detailed legal information about the use of FFmpeg inexternal programs read the @file{LICENSE} file in the source tree andconsult @url{https://ffmpeg.org/legal.html}. If you modify FFmpeg code for your own use case, you are highly encouraged to@emph{submit your changes back to us}, using this document as a guide. There areboth pragmatic and ideological reasons to do so:@itemize @bullet@itemMaintaining external changes to keep up with upstream development istime-consuming and error-prone. With your code in the main tree, it will bemaintained by FFmpeg developers.@itemFFmpeg developers include leading experts in the field who can find bugs ordesign flaws in your code.@itemBy supporting the project you find useful you ensure it continues to bemaintained and developed.@end itemize All proposed code changes should be submitted for review to@url{mailto:ffmpeg-devel@@ffmpeg.org, the development mailing list}, asdescribed in more detail in the @ref{Submitting patches} chapter. The codeshould comply with the @ref{Development Policy} and follow the @ref{Coding Rules}.The developer making the commit and the author are responsible for their changesand should try to fix issues their commit causes. @anchor{Coding Rules}@chapter Coding Rules @section Language FFmpeg is mainly programmed in the ISO C11 language, except for the publicheaders which must stay C99 compatible. Compiler-specific extensions may be used with good reason, but must not bedepended on, i.e. the code must still compile and work with compilers lackingthe extension. The following C99 features must not be used anywhere in the codebase:@itemize @bullet@itemvariable-length arrays; @itemcomplex numbers; @itemmixed statements and declarations.@end itemize @subsection SIMD/DSP@anchor{SIMD/DSP} As modern compilers are unable to generate efficient SIMD or otherperformance-critical DSP code from plain C, handwritten assembly is used.Usually such code is isolated in a separate function. Then the standard approachis writing multiple versions of this function – a plain C one that workseverywhere and may also be useful for debugging, and potentially multiplearchitecture-specific optimized implementations. Initialization code thenchooses the best available version at runtime and loads it into a functionpointer; the function in question is then always called through this pointer. The specific syntax used for writing assembly is:@itemize @bullet@itemNASM on x86; @itemGAS on ARM and RISC-V.@end itemize A unit testing framework for assembly called @code{checkasm} lives under@file{tests/checkasm}. All new assembly should come with @code{checkasm} tests;adding tests for existing assembly that lacks them is also strongly encouraged. @subsection Other languages Other languages than C may be used in special cases:@itemize @bullet@itemCompiler intrinsics or inline assembly when the code in question cannot bewritten in the standard way described in the @ref{SIMD/DSP} section. Thistypically applies to code that needs to be inlined. @itemObjective-C where required for interacting with macOS-specific interfaces.@end itemize @section Code formatting conventions There are the following guidelines regarding the code style in files: @itemize @bullet@itemIndent size is 4. @itemThe TAB character is forbidden outside of Makefiles as is anyform of trailing whitespace. Commits containing either will berejected by the git repository. @itemYou should try to limit your code lines to 80 characters; however, do so ifand only if this improves readability. @itemK&R coding style is used.@end itemizeThe presentation is one inspired by 'indent -i4 -kr -nut'. @subsection ExamplesSome notable examples to illustrate common code style in FFmpeg: @itemize @bullet @itemSpace around assignments and after@code{if}/@code{do}/@code{while}/@code{for} keywords: @example c, good// Goodif (condition)    av_foo();@end example @example c, good// Goodfor (size_t i = 0; i < len; i++)    av_bar(i);@end example @example c, good// Goodsize_t size = 0;@end example However no spaces between the parentheses and condition, unless it helpsreadability of complex conditions, so the following should not be done: @example c, bad// Bad styleif ( condition )    av_foo();@end example @itemNo unnecessary parentheses, unless it helps readability: @example c, good// Goodint fields = ilace ? 2 : 1;@end example @itemNo braces around single-line blocks: @example c, good// Goodif (bits_pixel == 24)    avctx->pix_fmt = AV_PIX_FMT_BGR24;else if (bits_pixel == 8)    avctx->pix_fmt = AV_PIX_FMT_GRAY8;else @{    av_log(avctx, AV_LOG_ERROR, "Invalid pixel format.\n");    return AVERROR_INVALIDDATA;@}@end example @itemAvoid assignments in conditions where it makes sense: @example c, good// Goodvideo_enc->chroma_intra_matrix = av_mallocz(sizeof(*video_enc->chroma_intra_matrix) * 64)if (!video_enc->chroma_intra_matrix)    return AVERROR(ENOMEM);@end example @example c, bad// Bad styleif (!(video_enc->chroma_intra_matrix = av_mallocz(sizeof(*video_enc->chroma_intra_matrix) * 64)))    return AVERROR(ENOMEM);@end example @example c, good// Okwhile ((entry = av_dict_iterate(options, entry)))    av_log(ctx, AV_LOG_INFO, "Item '%s': '%s'\n", entry->key, entry->value);@end example @itemWhen declaring a pointer variable, the @code{*} goes with the variable not the type: @example c, good// GoodAVStream *stream;@end example @example c, bad// Bad styleAVStream* stream;@end example @end itemize If you work on a file that does not follow these guidelines consistently,change the parts that you are editing to follow these guidelines but donot make unrelated changes in the file to make it conform to these. @subsection Vim configurationIn order to configure Vim to follow FFmpeg formatting conventions, pastethe following snippet into your @file{.vimrc}:@example" indentation rules for FFmpeg: 4 spaces, no tabsset expandtabset shiftwidth=4set softtabstop=4set cindentset cinoptions=(0" Allow tabs in Makefiles.autocmd FileType make,automake set noexpandtab shiftwidth=8 softtabstop=8" Trailing whitespace and tabs are forbidden, so highlight them.highlight ForbiddenWhitespace ctermbg=red guibg=redmatch ForbiddenWhitespace /\s\+$\|\t/" Do not highlight spaces at the end of line while typing on that line.autocmd InsertEnter * match ForbiddenWhitespace /\t\|\s\+\%#\@@<!$/@end example @subsection Emacs configurationFor Emacs, add these roughly equivalent lines to your @file{.emacs.d/init.el}:@lisp(c-add-style "ffmpeg"             '("k&r"               (c-basic-offset . 4)               (indent-tabs-mode . nil)               (show-trailing-whitespace . t)               (c-offsets-alist                (statement-cont . (c-lineup-assignments +)))               )             )(setq c-default-style "ffmpeg")@end lisp @section CommentsUse the JavaDoc/Doxygen  format (see examples below) so that code documentationcan be generated automatically. All nontrivial functions should have a commentabove them explaining what the function does, even if it is just one sentence.All structures and their member variables should be documented, too. Avoid Qt-style and similar Doxygen syntax with @code{!} in it, i.e. replace@code{//!} with @code{///} and similar.  Also @@ syntax should be employedfor markup commands, i.e. use @code{@@param} and not @code{\param}. @example/** * @@file * MPEG codec. * @@author ... */ /** * Summary sentence. * more text ... * ... */typedef struct Foobar @{    int var1; /**< var1 description */    int var2; ///< var2 description    /** var3 description */    int var3;@} Foobar; /** * Summary sentence. * more text ... * ... * @@param my_parameter description of my_parameter * @@return return value description */int myfunc(int my_parameter)...@end example @anchor{Naming conventions}@section Naming conventions Names of functions, variables, and struct members must be lowercase, usingunderscores (_) to separate words. For example, @samp{avfilter_get_video_buffer}is an acceptable function name and @samp{AVFilterGetVideo} is not. Struct, union, enum, and typedeffed type names must use CamelCase. All structsand unions should be typedeffed to the same name as the struct/union tag, e.g.@code{typedef struct AVFoo @{ ... @} AVFoo;}. Enums are typically nottypedeffed. Enumeration constants and macros must be UPPERCASE, except for macrosmasquerading as functions, which should use the function naming convention. All identifiers in the libraries should be namespaced as follows:@itemize @bullet@itemNo namespacing for identifiers with file and lower scope (e.g. local variables,static functions), and struct and union members, @itemThe @code{ff_} prefix must be used for variables and functions visible outsideof file scope, but only used internally within a single library, e.g.@samp{ff_w64_demuxer}. This prevents name collisions when FFmpeg is staticallylinked. @itemFor variables and functions visible outside of file scope, used internallyacross multiple libraries, use @code{avpriv_} as prefix, for example,@samp{avpriv_report_missing_feature}. @itemAll other internal identifiers, like private type or macro names, should benamespaced only to avoid possible internal conflicts. E.g. @code{H264_NAL_SPS}vs. @code{HEVC_NAL_SPS}. @itemEach library has its own prefix for public symbols, in addition to thecommonly used @code{av_} (@code{avformat_} for libavformat,@code{avcodec_} for libavcodec, @code{swr_} for libswresample, etc).Check the existing code and choose names accordingly. @itemOther public identifiers (struct, union, enum, macro, type names) must use theirlibrary's public prefix (@code{AV}, @code{Sws}, or @code{Swr}).@end itemize Furthermore, name space reserved for the system should not be invaded.Identifiers ending in @code{_t} are reserved by@url{http://pubs.opengroup.org/onlinepubs/007904975/functions/xsh_chap02_02.html#tag_02_02_02, POSIX}.Also avoid names starting with @code{__} or @code{_} followed by an uppercaseletter as they are reserved by the C standard. Names starting with @code{_}are reserved at the file level and may not be used for externally visiblesymbols. If in doubt, just avoid names starting with @code{_} altogether. @section Miscellaneous conventions @itemize @bullet@itemCasts should be used only when necessary. Unneeded parenthesesshould also be avoided if they don't make the code easier to understand.@end itemize @anchor{Development Policy}@chapter Development Policy @section Code behaviour @subheading CorrectnessThe code must be valid. It must not crash, abort, access invalid pointers, leakmemory, cause data races or signed integer overflow, or otherwise causeundefined behaviour. Error codes should be checked and, when applicable,forwarded to the caller. @subheading Thread- and library-safetyOur libraries may be called by multiple independent callers in the same process.These calls may happen from any number of threads and the different call sitesmay not be aware of each other - e.g. a user program may be calling ourlibraries directly, and use one or more libraries that also call our libraries.The code must behave correctly under such conditions. @subheading RobustnessThe code must treat as untrusted any bytestream received from a caller or readfrom a file, network, etc. It must not misbehave when arbitrary data is sent toit - typically it should print an error message and return@code{AVERROR_INVALIDDATA} on encountering invalid input data. @subheading Memory allocationThe code must use the @code{av_malloc()} family of functions from@file{libavutil/mem.h} to perform all memory allocation, except in special cases(e.g. when interacting with an external library that requires a specificallocator to be used). All allocations should be checked and @code{AVERROR(ENOMEM)} returned onfailure. A common mistake is that error paths leak memory - make sure that doesnot happen. @subheading stdioOur libraries must not access the stdio streams stdin/stdout/stderr directly(e.g. via @code{printf()} family of functions), as that is not library-safe. Forlogging, use @code{av_log()}. @section Patches/Committing@subheading Licenses for patches must be compatible with FFmpeg.Contributions should be licensed under the@uref{http://www.gnu.org/licenses/lgpl-2.1.html, LGPL 2.1},including an "or any later version" clause, or, if you prefera gift-style license, the@uref{http://opensource.org/licenses/isc-license.txt, ISC} or@uref{http://mit-license.org/, MIT} license.@uref{http://www.gnu.org/licenses/gpl-2.0.html, GPL 2} includingan "or any later version" clause is also acceptable, but LGPL ispreferred.If you add a new file, give it a proper license header. Do not copy andpaste it from a random place, use an existing file as template. @subheading You must not commit code which breaks FFmpeg!This means unfinished code which is enabled and breaks compilation,or compiles but does not work/breaks the regression tests. Code whichis unfinished but disabled may be permitted under-circumstances, likemissing samples or an implementation with a small subset of features.Always check the mailing list for any reviewers with issues and testFATE before you push. @subheading Commit messagesCommit messages are highly important tools for informing other developers onwhat a given change does and why. Every commit must always have a properlyfilled out commit message with the following format:@examplearea changed: short 1 line description details describing what and why and giving references.@end example If the commit addresses a known bug on our bug tracker or other external issue(e.g. CVE), the commit message should include the relevant bug ID(s) or otherexternal identifiers. Note that this should be done in addition to a properexplanation and not instead of it. Comments such as "fixed!" or "Changed it."are not acceptable. When applying patches that have been discussed at length on the mailing list,reference the thread in the commit message. @subheading Testing must be adequate but not excessive.If it works for you, others, and passes FATE then it should be OK to commitit, provided it fits the other committing criteria. You should not worry aboutover-testing things. If your code has problems (portability, triggerscompiler bugs, unusual environment etc) they will be reported and eventuallyfixed. @subheading Do not commit unrelated changes together.They should be split them into self-contained pieces. Also do not forgetthat if part B depends on part A, but A does not depend on B, then A canand should be committed first and separate from B. Keeping changes wellsplit into self-contained parts makes reviewing and understanding them onthe commit log mailing list easier. This also helps in case of debugginglater on.Also if you have doubts about splitting or not splitting, do not hesitate toask/discuss it on the developer mailing list. @subheading Cosmetic changes should be kept in separate patches.We refuse source indentation and other cosmetic changes if they are mixedwith functional changes, such commits will be rejected and removed. Everydeveloper has his own indentation style, you should not change it. Of courseif you (re)write something, you can use your own style, even though we wouldprefer if the indentation throughout FFmpeg was consistent (Many projectsforce a given indentation style - we do not.). If you really need to makeindentation changes (try to avoid this), separate them strictly from realchanges. NOTE: If you had to put if()@{ .. @} over a large (> 5 lines) chunk of code,then either do NOT change the indentation of the inner part within (do notmove it to the right)! or do so in a separate commit @subheading Credit the author of the patch.Make sure the author of the commit is set correctly. (see git commit --author)If you apply a patch, send ananswer to ffmpeg-devel (or wherever you got the patch from) saying thatyou applied the patch. @subheading Credit any researchersIf a commit/patch fixes an issues found by some researcher, always credit theresearcher in the commit message for finding/reporting the issue. @subheading Always wait long enough before pushing changesDo NOT commit to code actively maintained by others without permission.Send a patch to ffmpeg-devel. If no one answers within a reasonabletime-frame (12h for build failures and security fixes, 3 days small changes,1 week for big patches) then commit your patch if you think it is OK.

Lines 1–500 of 1149. Load more