libcamera: Define constants for pixel formats in the public API

libcamera uses pixel format FourCC and modifier values from DRM. This
requires inclusion of drm_fourcc.h, creating a dependency on a header
that is packaged differently between distributions, and causing possible
issues with third-party applications.

Define constants for the supported pixel formats in the new formats.h
public API header, in order to remove the dependency on drm_fourcc.h.
The header is generated by a Python script from a list of supported
formats. The numerical values for the FourCC and modifier are extracted
from drm_fourcc.h by the script, ensuring that numerical values are not
inadvertently modified and preserving the direct interoperability.

The pixel formats constants can't be generated solely from drm_fourcc.h,
as that header defines FourCC values and modifier values, but doesn't
list the valid combinations. The supported formats are thus stored in a
YAML file, which contains the FourCC and optional modifier for each
supported format. We may later extend the YAML file to include formats
documentation, and possibly formats metadata to populate the
pixelFormatInfo map (in formats.cpp) automatically.

Now that two formats.h header are present (one in include/libcamera/ and
one in include/libcamera/internal/), we need to explicitly qualify the
Doxygen \file directive with a path.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>

3 files changed, 184 insertions, 0 deletions

diff --git a/include/libcamera/formats.h.in b/include/libcamera/formats.h.in
new file mode 100644
index 00000000..8e7b9581
--- /dev/null
+++ b/include/libcamera/formats.h.in
@@ -0,0 +1,44 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+/*
+ * Copyright (C) 2020, Google Inc.
+ *
+ * formats.h - Formats
+ *
+ * This file is auto-generated. Do not edit.
+ */
+#ifndef __LIBCAMERA_FORMATS_H__
+#define __LIBCAMERA_FORMATS_H__
+
+#include <stdint.h>
+
+#include <libcamera/pixel_format.h>
+
+namespace libcamera {
+
+namespace formats {
+
+namespace {
+
+constexpr uint32_t __fourcc(char a, char b, char c, char d)
+{
+	return (static_cast<uint32_t>(a) <<  0) |
+	       (static_cast<uint32_t>(b) <<  8) |
+	       (static_cast<uint32_t>(c) << 16) |
+	       (static_cast<uint32_t>(d) << 24);
+}
+
+constexpr uint64_t __mod(unsigned int vendor, unsigned int mod)
+{
+	return (static_cast<uint64_t>(vendor) << 56) |
+	       (static_cast<uint64_t>(mod) << 0);
+}
+
+} /* namespace */
+
+${formats}
+
+} /* namespace formats */
+
+} /* namespace libcamera */
+
+#endif /* __LIBCAMERA_FORMATS_H__ */
diff --git a/include/libcamera/gen-formats.py b/include/libcamera/gen-formats.py
new file mode 100755
index 00000000..60dcecc3
--- /dev/null
+++ b/include/libcamera/gen-formats.py
@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-2.0-or-later
+# Copyright (C) 2020, Google Inc.
+#
+# Author: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+#
+# gen-formats.py - Generate formats definitions from YAML
+
+import argparse
+import re
+import string
+import sys
+import yaml
+
+
+class DRMFourCC(object):
+    format_regex = re.compile(r"#define (DRM_FORMAT_[A-Z0-9_]+)[ \t]+fourcc_code\(('.', '.', '.', '.')\)")
+    mod_vendor_regex = re.compile(r"#define DRM_FORMAT_MOD_VENDOR_([A-Z0-9_]+)[ \t]+([0-9a-fA-Fx]+)")
+    mod_regex = re.compile(r"#define ([A-Za-z0-9_]+)[ \t]+fourcc_mod_code\(([A-Z0-9_]+), ([0-9a-fA-Fx]+)\)")
+
+    def __init__(self, filename):
+        self.formats = {}
+        self.vendors = {}
+        self.mods = {}
+
+        for line in open(filename, 'rb').readlines():
+            line = line.decode('utf-8')
+
+            match = DRMFourCC.format_regex.match(line)
+            if match:
+                format, fourcc = match.groups()
+                self.formats[format] = fourcc
+                continue
+
+            match = DRMFourCC.mod_vendor_regex.match(line)
+            if match:
+                vendor, value = match.groups()
+                self.vendors[vendor] = int(value, 0)
+                continue
+
+            match = DRMFourCC.mod_regex.match(line)
+            if match:
+                mod, vendor, value = match.groups()
+                self.mods[mod] = (vendor, int(value, 0))
+                continue
+
+    def fourcc(self, name):
+        return self.formats[name]
+
+    def mod(self, name):
+        vendor, value = self.mods[name]
+        return self.vendors[vendor], value
+
+
+def generate_h(formats, drm_fourcc):
+    template = string.Template('constexpr PixelFormat ${name}{ __fourcc(${fourcc}), __mod(${mod}) };')
+
+    fmts = []
+
+    for format in formats:
+        name, format = format.popitem()
+
+        data = {
+            'name': name,
+            'fourcc': drm_fourcc.fourcc(format['fourcc']),
+            'mod': '0, 0',
+        }
+
+        mod = format.get('mod')
+        if mod:
+            data['mod'] = '%u, %u' % drm_fourcc.mod(mod)
+
+        fmts.append(template.substitute(data))
+
+    return {'formats': '\n'.join(fmts)}
+
+
+def fill_template(template, data):
+
+    template = open(template, 'rb').read()
+    template = template.decode('utf-8')
+    template = string.Template(template)
+    return template.substitute(data)
+
+
+def main(argv):
+
+    # Parse command line arguments
+    parser = argparse.ArgumentParser()
+    parser.add_argument('-o', dest='output', metavar='file', type=str,
+                        help='Output file name. Defaults to standard output if not specified.')
+    parser.add_argument('input', type=str,
+                        help='Input file name.')
+    parser.add_argument('template', type=str,
+                        help='Template file name.')
+    parser.add_argument('drm_fourcc', type=str,
+                        help='Path to drm_fourcc.h.')
+    args = parser.parse_args(argv[1:])
+
+    data = open(args.input, 'rb').read()
+    formats = yaml.safe_load(data)['formats']
+    drm_fourcc = DRMFourCC(args.drm_fourcc)
+
+    data = generate_h(formats, drm_fourcc)
+    data = fill_template(args.template, data)
+
+    if args.output:
+        output = open(args.output, 'wb')
+        output.write(data.encode('utf-8'))
+        output.close()
+    else:
+        sys.stdout.write(data)
+
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv))
diff --git a/include/libcamera/meson.build b/include/libcamera/meson.build
index 73c5b999..cdb8e037 100644
--- a/include/libcamera/meson.build
+++ b/include/libcamera/meson.build
@@ -29,6 +29,11 @@ subdir('ipa')
 install_headers(libcamera_public_headers,
                 subdir : include_dir)
 
+#
+# Generate headers from templates.
+#
+
+# control_ids.h and property_ids.h
 gen_controls = files('../../src/libcamera/gen-controls.py')
 
 control_source_files = [
@@ -51,6 +56,22 @@ endforeach
 
 libcamera_public_headers += control_headers
 
+# formats.h
+gen_formats = files('gen-formats.py')
+
+formats_h = custom_target('formats_h',
+                          input : files(
+                              '../../src/libcamera/formats.yaml',
+                              'formats.h.in',
+                              '../linux/drm_fourcc.h'
+                          ),
+                          output : 'formats.h',
+                          command : [gen_formats, '-o', '@OUTPUT@', '@INPUT@'],
+                          install : true,
+                          install_dir : join_paths('include', include_dir))
+libcamera_public_headers += formats_h
+
+# libcamera.h
 gen_header = files('gen-header.sh')
 
 libcamera_h = custom_target('gen-header',
@@ -62,6 +83,7 @@ libcamera_h = custom_target('gen-header',
 
 libcamera_public_headers += libcamera_h
 
+# version.h
 version = libcamera_version.split('.')
 libcamera_version_config = configuration_data()
 libcamera_version_config.set('LIBCAMERA_VERSION_MAJOR', version[0])