ny new public identifiers in installed headers are considered new API - this includes new functions, structs, macros, enum values, typedefs, new fields in existing structs, new installed headers, etc. Consider the following guidelines when adding new APIs.
Motivation
While new APIs can be added relatively easily, changing or removing them is much harder due to abovementioned compatibility requirements. You should then consider carefully whether the functionality you are adding really needs to be exposed to our callers as new public API.
Your new API should have at least one well-established use case outside of the library that cannot be easily achieved with existing APIs. Every library in FFmpeg also has a defined scope - your new API must fit within it.
Replacing existing APIs
If your new API is replacing an existing one, it should be strictly superior to it, so that the advantages of using the new API outweight the cost to the callers of changing their code. After adding the new API you should then deprecate the old one and schedule it for removal, as described in Removing interfaces.
If you deem an existing API deficient and want to fix it, the preferred approach in most cases is to add a differently-named replacement and deprecate the existing API rather than modify it. It is important to make the changes visible to our callers (e.g. through compile- or run-time deprecation warnings) and make it clear how to transition to the new API (e.g. in the Doxygen documentation or on the wiki).
API design
The FFmpeg libraries are used by a variety of callers to perform a wide range of multimedia-related processing tasks. You should therefore - within reason - try to design your new API for the broadest feasible set of use cases and avoid unnecessarily limiting it to a specific type of callers (e.g. just media playback or just transcoding).
Consistency
Check whether similar APIs already exist in FFmpeg. If they do, try to model your new addition on them to achieve better overall consistency.
The naming of your new identifiers should follow the Naming conventions and be aligned with other similar APIs, if applicable.
Extensibility
You should also consider how your API might be extended in the future in a backward-compatible way. If you are adding a new struct AVFoo, the standard approach is requiring the caller to always allocate it through a constructor function, typically named av_foo_alloc(). This way new fields may be added to the end of the struct without breaking ABI compatibility. Typically you will also want a destructor - av_foo_free(AVFoo**) that frees the indirectly supplied object (and its contents, if applicable) and writes NULL to the supplied pointer, thus eliminating the potential dangling pointer in the caller’s memory.
If you are adding new functions, consider whether it might be desirable to tweak their behavior in the future - you may want to add a flags argument, even though it would be unused initially.
Documentation
All new APIs must be documented as Doxygen-formatted comments above the identifiers you add to the public headers. You should also briefly mention the change in doc/APIchanges.
Bump the version
Backward-incompatible API or ABI changes require incrementing (bumping) the major version number, as described in Major version bumps. Major bumps are significant events that happen on a schedule - so if your change strictly requires one you should add it under #if preprocesor guards that disable it until the next major bump happens.
New APIs that can be added without breaking API or ABI compatibility require bumping the minor version number.
Incrementing the third (micro) version component means a noteworthy binary compatible change (e.g. encoder bug fix that matters for the decoder). The third component always starts at 100 to distinguish FFmpeg from Libav.
标签:Adding,ffmpeg,APIs,interfaces,should,API,new,existing,your From: https://www.cnblogs.com/sathcal/p/18537801