lavc/videotoolboxenc: better compat_keys docs

Added more specific docs about when to use compat_keys, and how to
add new constants.

Signed-off-by: Rick Kern <kernrj@gmail.com>

1 files changed, 13 insertions, 3 deletions

diff --git a/libavcodec/videotoolboxenc.c b/libavcodec/videotoolboxenc.c
index b0297ec448..e93d45e151 100644
--- a/libavcodec/videotoolboxenc.c
+++ b/libavcodec/videotoolboxenc.c
@@ -64,9 +64,19 @@ typedef OSStatus (*getParameterSetAtIndex)(CMFormatDescriptionRef videoDesc,
                                            int *NALUnitHeaderLengthOut);
 
 /*
- * Keys that are not present in all versions of VideoToolbox need to be
- * accessed from compat_keys, or it will cause compiler errors when compiling
- * for older OS versions.
+ * Symbols that aren't available in MacOS 10.8 and iOS 8.0 need to be accessed
+ * from compat_keys, or it will cause compiler errors when compiling for older
+ * OS versions.
+ *
+ * For example, kVTCompressionPropertyKey_H264EntropyMode was added in
+ * MacOS 10.9. If this constant were used directly, a compiler would generate
+ * an error when it has access to the MacOS 10.8 headers, but does not have
+ * 10.9 headers.
+ *
+ * Runtime errors will still occur when unknown keys are set. A warning is
+ * logged and encoding continues where possible.
+ *
+ * When adding new symbols, they should be loaded/set in loadVTEncSymbols().
  */
 static struct{
     CFStringRef kCVImageBufferColorPrimaries_ITU_R_2020;