From fc706276c051c425538d1476a7be05442d06dd0f Mon Sep 17 00:00:00 2001
From: Anton Khirnov <anton@khirnov.net>
Date: Sun, 3 Mar 2024 16:42:47 +0100
Subject: [PATCH] lavu/opt: distinguish between native and foreign access for
 AVOption fields

Native access is from the code that declared the options, foreign access
is from code that is using the options. Forbid foreign access to
AVOption.offset/default_val, for which there is no good reason, and
which should allow us more freedom in extending their semantics in a
compatible way.
---
 libavutil/opt.h | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/libavutil/opt.h b/libavutil/opt.h
index 91024da022..82bca920fb 100644
--- a/libavutil/opt.h
+++ b/libavutil/opt.h
@@ -43,6 +43,16 @@
  * ("objects"). An option can have a help text, a type and a range of possible
  * values. Options may then be enumerated, read and written to.
  *
+ * There are two modes of access to members of AVOption and its child structs.
+ * One is called 'native access', and refers to access from the code that
+ * declares the AVOption in question.  The other is 'foreign access', and refers
+ * to access from other code.
+ *
+ * Certain struct members in this header are documented as 'native access only'
+ * or similar - it means that only the code that declared the AVOption in
+ * question is allowed to access the field. This allows us to extend the
+ * semantics of those fields without breaking API compatibility.
+ *
  * @section avoptions_implement Implementing AVOptions
  * This section describes how to add AVOptions capabilities to a struct.
  *
@@ -298,6 +308,8 @@ typedef struct AVOption {
     const char *help;
 
     /**
+     * Native access only.
+     *
      * The offset relative to the context structure where the option
      * value is stored. It should be 0 for named constants.
      */
@@ -305,6 +317,8 @@ typedef struct AVOption {
     enum AVOptionType type;
 
     /**
+     * Native access only.
+     *
      * the default value for scalar options
      */
     union {