[FFmpeg-cvslog] lavc/videotoolboxenc: better compat_keys docs

[Rick Kern]

ffmpeg | branch: master | Rick Kern <kernrj at gmail.com> | Sat May 20 11:35:51 2023 -0400| [902c949d309e3ef304775d1970ea77b04904f2bc] | committer: Rick Kern

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 at gmail.com>

> http://git.videolan.org/gitweb.cgi/ffmpeg.git/?a=commit;h=902c949d309e3ef304775d1970ea77b04904f2bc
---

 libavcodec/videotoolboxenc.c | 16 +++++++++++++---
 1 file 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;