gstreamer: Generate controls from control_ids_*.yaml files

This commit implements gstreamer controls for the libcamera element by
generating the controls from the control_ids_*.yaml files using a new
gen-gst-controls.py script. The appropriate meson files are also changed
to automatically run the script when building.

The gen-gst-controls.py script works similar to the gen-controls.py
script by parsing the control_ids_*.yaml files and generating C++ code
for each exposed control.
For the controls to be used as gstreamer properties the type for each
control needs to be translated to the appropriate glib type and a
GEnumValue is generated for each enum control. Then a
g_object_install_property(), _get_property() and _set_property()
function is generated for each control.
The vendor controls get prefixed with "$vendor-" in the final gstreamer
property name.

The C++ code generated by the gen-gst-controls.py script is written into
the template gstlibcamerasrc-controls.cpp.in file. The matching
gstlibcamerasrc-controls.h header defines the GstCameraControls class
which handles the installation of the gstreamer properties as well as
keeping track of the control values and setting and getting the
controls. The content of these functions is generated in the Python
script.

Finally the libcamerasrc element itself is edited to make use of the new
GstCameraControls class. The way this works is by defining a PROP_LAST
enum variant which is passed to the installProperties() function so the
properties are defined with the appropriate offset. When getting or
setting a property PROP_LAST is subtracted from the requested property
to translate the control back into a libcamera::controls:: enum
variant.

Signed-off-by: Jaslo Ziska <jaslo@ziska.de>
Reviewed-by: Nicolas Dufresne <nicolas.dufresne@collabora.com>
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>

3 files changed, 191 insertions, 0 deletions

diff --git a/utils/codegen/controls.py b/utils/codegen/controls.py
index 7bafee59..03c77cc6 100644
--- a/utils/codegen/controls.py
+++ b/utils/codegen/controls.py
@@ -110,3 +110,11 @@ class Control(object):
             return f"Span<const {typ}, {self.__size}>"
         else:
             return f"Span<const {typ}>"
+
+    @property
+    def element_type(self):
+        return self.__data.get('type')
+
+    @property
+    def size(self):
+        return self.__size
diff --git a/utils/codegen/gen-gst-controls.py b/utils/codegen/gen-gst-controls.py
new file mode 100755
index 00000000..2601a675
--- /dev/null
+++ b/utils/codegen/gen-gst-controls.py
@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-2.0-or-later
+# Copyright (C) 2019, Google Inc.
+# Copyright (C) 2024, Jaslo Ziska
+#
+# Authors:
+# Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+# Jaslo Ziska <jaslo@ziska.de>
+#
+# Generate gstreamer control properties from YAML
+
+import argparse
+import jinja2
+import re
+import sys
+import yaml
+
+from controls import Control
+
+
+exposed_controls = [
+    'AeEnable', 'AeMeteringMode', 'AeConstraintMode', 'AeExposureMode',
+    'ExposureValue', 'ExposureTime', 'AnalogueGain', 'AeFlickerPeriod',
+    'Brightness', 'Contrast', 'AwbEnable', 'AwbMode', 'ColourGains',
+    'Saturation', 'Sharpness', 'ColourCorrectionMatrix', 'ScalerCrop',
+    'DigitalGain', 'AfMode', 'AfRange', 'AfSpeed', 'AfMetering', 'AfWindows',
+    'LensPosition', 'Gamma',
+]
+
+
+def find_common_prefix(strings):
+    prefix = strings[0]
+
+    for string in strings[1:]:
+        while string[:len(prefix)] != prefix and prefix:
+            prefix = prefix[:len(prefix) - 1]
+        if not prefix:
+            break
+
+    return prefix
+
+
+def format_description(description):
+    # Substitute doxygen keywords \sa (see also) and \todo
+    description = re.sub(r'\\sa((?: \w+)+)',
+                         lambda match: 'See also: ' + ', '.join(
+                             map(kebab_case, match.group(1).strip().split(' '))
+                         ) + '.', description)
+    description = re.sub(r'\\todo', 'Todo:', description)
+
+    description = description.strip().split('\n')
+    return '\n'.join([
+        '"' + line.replace('\\', r'\\').replace('"', r'\"') + ' "' for line in description if line
+    ]).rstrip()
+
+
+# Custom filter to allow indenting by a string prior to Jinja version 3.0
+#
+# This function can be removed and the calls to indent_str() replaced by the
+# built-in indent() filter when dropping Jinja versions older than 3.0
+def indent_str(s, indention):
+    s += '\n'
+
+    lines = s.splitlines()
+    rv = lines.pop(0)
+
+    if lines:
+        rv += '\n' + '\n'.join(
+            indention + line if line else line for line in lines
+        )
+
+    return rv
+
+
+def snake_case(s):
+    return ''.join([
+        c.isupper() and ('_' + c.lower()) or c for c in s
+    ]).strip('_')
+
+
+def kebab_case(s):
+    return snake_case(s).replace('_', '-')
+
+
+def extend_control(ctrl):
+    if ctrl.vendor != 'libcamera':
+        ctrl.namespace = f'{ctrl.vendor}::'
+        ctrl.vendor_prefix = f'{ctrl.vendor}-'
+    else:
+        ctrl.namespace = ''
+        ctrl.vendor_prefix = ''
+
+    ctrl.is_array = ctrl.size is not None
+
+    if ctrl.is_enum:
+        # Remove common prefix from enum variant names
+        prefix = find_common_prefix([enum.name for enum in ctrl.enum_values])
+        for enum in ctrl.enum_values:
+            enum.gst_name = kebab_case(enum.name.removeprefix(prefix))
+
+        ctrl.gtype = 'enum'
+        ctrl.default = '0'
+    elif ctrl.element_type == 'bool':
+        ctrl.gtype = 'boolean'
+        ctrl.default = 'false'
+    elif ctrl.element_type == 'float':
+        ctrl.gtype = 'float'
+        ctrl.default = '0'
+        ctrl.min = '-G_MAXFLOAT'
+        ctrl.max = 'G_MAXFLOAT'
+    elif ctrl.element_type == 'int32_t':
+        ctrl.gtype = 'int'
+        ctrl.default = '0'
+        ctrl.min = 'G_MININT'
+        ctrl.max = 'G_MAXINT'
+    elif ctrl.element_type == 'int64_t':
+        ctrl.gtype = 'int64'
+        ctrl.default = '0'
+        ctrl.min = 'G_MININT64'
+        ctrl.max = 'G_MAXINT64'
+    elif ctrl.element_type == 'uint8_t':
+        ctrl.gtype = 'uchar'
+        ctrl.default = '0'
+        ctrl.min = '0'
+        ctrl.max = 'G_MAXUINT8'
+    elif ctrl.element_type == 'Rectangle':
+        ctrl.is_rectangle = True
+        ctrl.default = '0'
+        ctrl.min = '0'
+        ctrl.max = 'G_MAXINT'
+    else:
+        raise RuntimeError(f'The type `{ctrl.element_type}` is unknown')
+
+    return ctrl
+
+
+def main(argv):
+    # Parse command line arguments
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--output', '-o', metavar='file', type=str,
+                        help='Output file name. Defaults to standard output if not specified.')
+    parser.add_argument('--template', '-t', dest='template', type=str, required=True,
+                        help='Template file name.')
+    parser.add_argument('input', type=str, nargs='+',
+                        help='Input file name.')
+
+    args = parser.parse_args(argv[1:])
+
+    controls = {}
+    for input in args.input:
+        data = yaml.safe_load(open(input, 'rb').read())
+
+        vendor = data['vendor']
+        ctrls = controls.setdefault(vendor, [])
+
+        for ctrl in data['controls']:
+            ctrl = Control(*ctrl.popitem(), vendor)
+
+            if ctrl.name in exposed_controls:
+                ctrls.append(extend_control(ctrl))
+
+    data = {'controls': list(controls.items())}
+
+    env = jinja2.Environment()
+    env.filters['format_description'] = format_description
+    env.filters['indent_str'] = indent_str
+    env.filters['snake_case'] = snake_case
+    env.filters['kebab_case'] = kebab_case
+    template = env.from_string(open(args.template, 'r', encoding='utf-8').read())
+    string = template.render(data)
+
+    if args.output:
+        with open(args.output, 'w', encoding='utf-8') as output:
+            output.write(string)
+    else:
+        sys.stdout.write(string)
+
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv))
diff --git a/utils/codegen/meson.build b/utils/codegen/meson.build
index adf33bba..904dd66d 100644
--- a/utils/codegen/meson.build
+++ b/utils/codegen/meson.build
@@ -11,6 +11,7 @@ py_modules += ['jinja2', 'yaml']
 
 gen_controls = files('gen-controls.py')
 gen_formats = files('gen-formats.py')
+gen_gst_controls = files('gen-gst-controls.py')
 gen_header = files('gen-header.sh')
 gen_ipa_pub_key = files('gen-ipa-pub-key.py')
 gen_tracepoints = files('gen-tp-header.py')