Proposal: Feature control for variable COLRv1

* include/freetype/ftdriver.h (variable-color-v1 property): Add documentation
for variable-colr-v1 property.
* src/truetype/ttdriver.c (tt_property_set): Ingest variable-control property
when called, set to enable_variable_colrv1 driver flag.
* src/truetype/ttobjs.h (TT_DriverRec): Add enable_variable_colrv1 flag.

3 files changed, 64 insertions, 3 deletions

diff --git a/include/freetype/ftdriver.h b/include/freetype/ftdriver.h
index 0dc91e8b4..3de6c6b7a 100644
--- a/include/freetype/ftdriver.h
+++ b/include/freetype/ftdriver.h
@@ -214,9 +214,9 @@ FT_BEGIN_HEADER
    *   itself, it is possible to control its behaviour with @FT_Property_Set
    *   and @FT_Property_Get.
    *
-   *   The TrueType driver's module name is 'truetype'; a single property
-   *   @interpreter-version is available, as documented in the @properties
-   *   section.
+   *   The TrueType driver's module name is 'truetype'; two properties are
+   *   available, @interpreter-version and @TEMPORARY-enable-variable-colrv1, as
+   *   documented in the @properties section.
    *
    *   To help understand the differences between interpreter versions, we
    *   introduce a list of definitions, kindly provided by Greg Hitchcock.
@@ -820,6 +820,48 @@ FT_BEGIN_HEADER
    *   2.5
    */
 
+  /**************************************************************************
+   *
+   * @property:
+   *   TEMPORARY-enable-variable-colrv1
+   *
+   * @description:
+   *   Controls experimental support of variable COLRv1 and whether the COLRv1
+   *   implementation should take into account variation deltas. This tells the
+   *   COLRv1 API methods whether they should read from the font and apply
+   *   variable deltas to COLRv1 properties. The feature is default off.  When
+   *   on, variable COLRv1 deltas are applied for COLRv1 features for which they
+   *   are already implemented. When off, variable deltas are ignored even if
+   *   the respective PaintVar* table may already be understood.
+   *
+   *   WARNING: Temporary flag during development of variable COLRv1. This flag
+   *   will be removed, do not rely on it. Full variable COLRv1 support will be
+   *   announced separately.
+   *
+   * @note:
+   *   This property cannot be set via the `FREETYPE_PROPERTIES` environment
+   *   variable.
+   *
+   * @example:
+   *   The following example code demonstrates how to enable variable
+   *   COLRv1.
+   *
+   *   ```
+   *     FT_Library  library;
+   *     FT_Face     face;
+   *     FT_Bool     variable_colrv1 = TRUE;
+   *
+   *
+   *     FT_Init_FreeType( &library );
+   *
+   *     FT_Property_Set( library, "truetype",
+   *                               "TEMPORARY-enable-variable-colrv1",
+   *                               &variable_colr_v1 );
+   *   ```
+   *
+   * @since:
+   *   2.12.2
+   */
 
   /**************************************************************************
    *
diff --git a/src/truetype/ttdriver.c b/src/truetype/ttdriver.c
index 31dcb3c6f..dc063bbb3 100644
--- a/src/truetype/ttdriver.c
+++ b/src/truetype/ttdriver.c
@@ -108,6 +108,23 @@
       return error;
     }
 
+    if ( !ft_strcmp( property_name, "TEMPORARY-enable-variable-colrv1" ) )
+    {
+      /* This flag is temporary and can't be set with environment variables. */
+      if ( !value_is_string )
+      {
+        FT_Bool*  bv = (FT_Bool*)value;
+
+        if ( *bv == TRUE || *bv == FALSE)
+          driver->enable_variable_colrv1 = *bv;
+        else
+          error = FT_ERR( Unimplemented_Feature );
+      } else
+        error = FT_ERR( Invalid_Argument );
+
+      return error;
+    }
+
     FT_TRACE2(( "tt_property_set: missing property `%s'\n",
                 property_name ));
     return FT_THROW( Missing_Property );
diff --git a/src/truetype/ttobjs.h b/src/truetype/ttobjs.h
index 5fa239d43..b1366fc63 100644
--- a/src/truetype/ttobjs.h
+++ b/src/truetype/ttobjs.h
@@ -337,6 +337,8 @@ FT_BEGIN_HEADER
 
     FT_UInt  interpreter_version;
 
+    FT_Bool  enable_variable_colrv1;
+
   } TT_DriverRec;