[libcamera-devel] [PATCH v4 03/10] libcamera: properties: Generate libcamera properties
Jacopo Mondi
jacopo at jmondi.org
Thu Jan 9 00:25:09 CET 2020
Re-use the Control generation infrastructure to generate libcamera properties.
Introduce three additional files:
- include/libcamera/property_ids.h
Defines the properties ids
- src/libcamera/property_ids.cpp
Defines the properties Control<> instances
- src/libcamera/property_ids.yaml
Provide properties definitions
Signed-off-by: Jacopo Mondi <jacopo at jmondi.org>
---
Resending a new version as in the previoud rotation could had been defined in a
way which required to use signed values, which is not nice.
I've redefined here all rotation in counterclockwise direction, removing the
need for a sign.
Please look at this one and ignore the previous version.
Thanks
j
---
include/libcamera/meson.build | 26 ++-
include/libcamera/property_ids.h.in | 33 +++
src/libcamera/meson.build | 21 +-
src/libcamera/property_ids.cpp.in | 43 ++++
src/libcamera/property_ids.yaml | 336 ++++++++++++++++++++++++++++
5 files changed, 442 insertions(+), 17 deletions(-)
create mode 100644 include/libcamera/property_ids.h.in
create mode 100644 src/libcamera/property_ids.cpp.in
create mode 100644 src/libcamera/property_ids.yaml
diff --git a/include/libcamera/meson.build b/include/libcamera/meson.build
index 99abf0609940..25f503660960 100644
--- a/include/libcamera/meson.build
+++ b/include/libcamera/meson.build
@@ -23,15 +23,23 @@ install_headers(libcamera_api,
gen_controls = files('../../src/libcamera/gen-controls.py')
-control_ids_h = custom_target('control_ids_h',
- input : files('../../src/libcamera/control_ids.yaml', 'control_ids.h.in'),
- output : 'control_ids.h',
- depend_files : gen_controls,
- command : [gen_controls, '-o', '@OUTPUT@', '@INPUT@'],
- install : true,
- install_dir : join_paths('include', include_dir))
-
-libcamera_api += control_ids_h
+control_source_files = [
+ 'control_ids',
+ 'property_ids',
+]
+
+control_headers = []
+
+foreach header : control_source_files
+ input_files = files('../../src/libcamera/' + header +'.yaml', header + '.h.in')
+ control_headers += custom_target(header + '_h',
+ input : input_files,
+ output : header + '.h',
+ depend_files : gen_controls,
+ command : [gen_controls, '-o', '@OUTPUT@', '@INPUT@'],
+ install : true,
+ install_dir : join_paths('include', include_dir))
+endforeach
gen_header = files('gen-header.sh')
diff --git a/include/libcamera/property_ids.h.in b/include/libcamera/property_ids.h.in
new file mode 100644
index 000000000000..62799b3e8c54
--- /dev/null
+++ b/include/libcamera/property_ids.h.in
@@ -0,0 +1,33 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+/*
+ * Copyright (C) 2019, Google Inc.
+ *
+ * property_ids.h : Property ID list
+ *
+ * This file is auto-generated. Do not edit.
+ */
+
+#ifndef __LIBCAMERA_PROPERTY_IDS_H__
+#define __LIBCAMERA_PROPERTY_IDS_H__
+
+#include <stdint.h>
+
+#include <libcamera/controls.h>
+
+namespace libcamera {
+
+namespace properties {
+
+enum {
+${ids}
+};
+
+${controls}
+
+extern const ControlIdMap properties;
+
+} /* namespace propertiess */
+
+} /* namespace libcamera */
+
+#endif // __LIBCAMERA_PROPERTY_IDS_H__
diff --git a/src/libcamera/meson.build b/src/libcamera/meson.build
index c4f965bd7413..14aff6e5fc13 100644
--- a/src/libcamera/meson.build
+++ b/src/libcamera/meson.build
@@ -67,14 +67,19 @@ endif
gen_controls = files('gen-controls.py')
-control_ids_cpp = custom_target('control_ids_cpp',
- input : files('control_ids.yaml', 'control_ids.cpp.in'),
- output : 'control_ids.cpp',
- depend_files : gen_controls,
- command : [gen_controls, '-o', '@OUTPUT@', '@INPUT@'])
-
-libcamera_sources += control_ids_cpp
-libcamera_sources += control_ids_h
+control_sources = []
+
+foreach source : control_source_files
+ input_files = files(source +'.yaml', source + '.cpp.in')
+ control_sources += custom_target(source + '_cpp',
+ input : input_files,
+ output : source + '.cpp',
+ depend_files : gen_controls,
+ command : [gen_controls, '-o', '@OUTPUT@', '@INPUT@'])
+endforeach
+
+libcamera_sources += control_headers
+libcamera_sources += control_sources
gen_version = join_paths(meson.source_root(), 'utils', 'gen-version.sh')
diff --git a/src/libcamera/property_ids.cpp.in b/src/libcamera/property_ids.cpp.in
new file mode 100644
index 000000000000..bfdd823f63b0
--- /dev/null
+++ b/src/libcamera/property_ids.cpp.in
@@ -0,0 +1,43 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+/*
+ * Copyright (C) 2019, Google Inc.
+ *
+ * property_ids.cpp : Property ID list
+ *
+ * This file is auto-generated. Do not edit.
+ */
+
+#include <libcamera/property_ids.h>
+
+/**
+ * \file property_ids.h
+ * \brief Camera property identifiers
+ */
+
+namespace libcamera {
+
+/**
+ * \brief Namespace for libcamera properties
+ */
+namespace properties {
+
+${controls_doc}
+
+#ifndef __DOXYGEN__
+/*
+ * Keep the properties definitions hidden from doxygen as it incorrectly parses
+ * them as functions.
+ */
+${controls_def}
+#endif
+
+/**
+ * \brief List of all supported libcamera properties
+ */
+extern const ControlIdMap properties {
+${controls_map}
+};
+
+} /* namespace properties */
+
+} /* namespace libcamera */
diff --git a/src/libcamera/property_ids.yaml b/src/libcamera/property_ids.yaml
new file mode 100644
index 000000000000..b1bc6fed473c
--- /dev/null
+++ b/src/libcamera/property_ids.yaml
@@ -0,0 +1,336 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+#
+# Copyright (C) 2019, Google Inc.
+#
+%YAML 1.2
+---
+controls:
+ - Location:
+ type: int32_t
+ description: |
+ Camera mounting location
+ enum:
+ - CameraLocationFront:
+ value: 0
+ description: |
+ The camera is mounted on the front side of the device, facing the
+ user
+ - CameraLocationBack:
+ value: 1
+ description: |
+ The camera is mounted on the back facing side of the device
+ - CameraLocationExternal:
+ value: 2
+ description: |
+ The camera is attached to the device in a way that allows it to
+ move freely
+
+ - Rotation:
+ type: int32_t
+ description: |
+ The camera rotation is expressed as the angular difference in degrees
+ between two reference systems, one implicitly defined by the camera
+ module intrinsics characteristics, and one artificially defined on the
+ external world scene to be captured when projected on the image sensor
+ pixel array.
+
+ A camera sensor has an implicitly defined 2-dimensional reference
+ system 'Rc' defined by its pixel array scan-out order, with its origin
+ posed at pixel address (0,0), the x-axis progressing from there towards
+ the last scanned out column of the pixel array and the y-axis
+ progressing towards the last scanned out line.
+
+ A typical example for a sensor with a (2592x1944) pixel array matrix
+ observed from the front is
+
+ (2592) x-axis 0
+ <------------------------+ 0
+ .......... ... ..........!
+ .......... ... ..........! y-axis
+ ... !
+ .......... ... ..........!
+ .......... ... ..........! (1944)
+ V
+
+ The external world scene reference system scene 'Rs' is defined as a
+ 2-dimensional reference system on the parallel plane posed in front
+ of the camera module's focal plane, with its origin placed on the
+ visible top-left corner, the x-axis progressing towards the right from
+ there and the y-axis progressing towards the bottom of the visible
+ scene.
+
+ A typical example of a (very common) picture of a shark swimming from
+ left to right is
+
+ x-axis
+ (0,0)---------------------->
+ !
+ !
+ ! |\____)\___
+ ! ) _____ __`<
+ ! |/ )/
+ !
+ V
+ y-axis
+
+ With the reference plane posed in front of the camera module and
+ parallel to its focal plane
+
+ !
+ / !
+ / !
+ / !
+ _ / !
+ +-/ \-+ / !
+ | (o) | ! 'Rs' reference plane
+ +-----+ \ !
+ \ !
+ \ !
+ \ !
+ \ !
+ !
+
+ When projected on the sensor's pixel array, the image and the associated
+ reference system 'Rs' are typically inverted, due to the camera module's
+ lens optical inversion effect.
+
+ Assuming the above represented scene of the swimming shark, the lens
+ inversion projects on the sensor pixel array the reference plane 'Rp'
+
+ y-axis
+ ^
+ !
+ ! |\_____)\__
+ ! ) ____ ___.<
+ ! |/ )/
+ !
+ !
+ (0,0)---------------------->
+ x-axis
+
+ The camera rotation property is then defined as the angular difference
+ in counterclockwise direction between the origin of the camera reference
+ system 'Rc', defined by the camera sensor scan-out direction and its
+ mounting position, and the origin of the projected scene reference
+ system 'Rp', result of the optical projection of the scene reference
+ system 'Rs' on the sensor pixel array.
+
+ Examples
+
+ 0 degrees camera rotation
+
+ y-Rp
+ y-Rc ^
+ ^ !
+ ! !
+ ! !
+ ! !
+ ! !
+ ! !
+ ! (0,0)---------------------->
+ ! x-Rp
+ 0 +------------------------------------->
+ 0 x-Rc
+
+
+ x-Rc 0
+ <------------------------+ 0
+ x-Rp !
+ <-----------------------(0,0) !
+ ! !
+ ! !
+ ! !
+ ! V
+ ! y-Rc
+ V
+ y-Rp
+
+ 90 degrees camera rotation
+
+ 0 y-Rc
+ 0 +----------------------->
+ !
+ ! y-Rp
+ ! ^
+ ! !
+ ! !
+ ! !
+ ! !
+ ! !
+ ! !
+ ! (0,0)---------------------->
+ ! x-Rp
+ !
+ V
+ x-Rc
+
+ 180 degrees camera rotation
+
+ x-Cr 0
+ <------------------------+ 0
+ y-Rp !
+ ^ !
+ ! ! y-Cr
+ ! !
+ ! !
+ ! V
+ !
+ !
+ (0,0)--------------------->
+ x-Rp
+
+ 270 degrees camera rotation
+
+ 0 y-Rc
+ 0 +----------------------->
+ ! x-Rp
+ ! <-----------------------(0,0
+ ! !
+ ! !
+ ! !
+ ! !
+ ! !
+ ! V
+ ! y-Rp
+ !
+ !
+ V
+ x-Rc
+
+
+
+ Example one - Webcam
+
+ A camera module installed on the user facing part of a laptop screen
+ casing used for video calls. The captured images are meant to be
+ displayed in landscape mode (width > height) on the laptop screen.
+
+ The camera is typically mounted 180 degrees rotated to compensate the
+ lens optical inversion effect.
+
+ y-Rp
+ y-Rc ^
+ ^ !
+ ! ! |\_____)\__
+ ! ! ) ____ ___.<
+ ! ! |/ )/
+ ! !
+ ! !
+ ! (0,0)---------------------->
+ ! x-Rp
+ 0 +------------------------------------->
+ 0 x-Rc
+
+ The two reference systems are aligned, the resulting camera rotation is
+ 0 degrees, no rotation correction should be applied to the resulting
+ image once captured to memory buffers to correctly display it to users.
+
+ +--------------------------+
+ ! |\____)\___ !
+ ! ) _____ __`< !
+ ! |/ )/ !
+ +--------------------------+
+
+ If the camera module is not mounted 180 degrees rotated to compensate
+ the lens optical inversion, the two reference system will result not
+ aligned, with 'Rp' plane 180 degrees rotated in respect to the 'Rc'
+ plane.
+
+ x-Rc 0
+ <------------------------+ 0
+ y-Rp !
+ ^ !
+ ! ! y-Rc
+ ! |\_____)\__ !
+ ! ) ____ ___.< !
+ ! |/ )/ V
+ !
+ !
+ (0,0)--------------------->
+ x-Rp
+
+ The image once captured to memory will then be 180 degrees rotated
+
+ +--------------------------+
+ ! __/(_____/| !
+ ! >.___ ____ ( !
+ ! \( \| !
+ +--------------------------+
+
+ A software rotation correction of 180 degrees should be applied to
+ correctly display the image.
+
+ +--------------------------+
+ ! |\____)\___ !
+ ! ) _____ __`< !
+ ! |/ )/ !
+ +--------------------------+
+
+ Example two - Phone camera
+
+ A camera installed on the back-side of a mobile device facing away from
+ the user. The captured images are meant to be displayed in portrait mode
+ (height > width) to match the device screen orientation and the device
+ usage orientation used when taking the picture.
+
+ The camera is typically mounted with its pixel array longer side aligned
+ to the device longer side, 180 degrees rotated to compensate the lens
+ optical inversion effect.
+
+ 0 y-Rc
+ 0 +----------------------->
+ !
+ ! y-Rp
+ ! ^
+ ! !
+ ! ! |\_____)\__
+ ! ! ) ____ ___.<
+ ! ! |/ )/
+ ! !
+ ! !
+ ! (0,0)---------------------->
+ ! x-Rp
+ !
+ !
+ V
+ x-Rc
+
+ The two reference systems are not aligned and the 'Rp' reference
+ system is 90 degrees rotated in counterclockwise direction in respect
+ to the 'Rc' reference system.
+
+ The image, when captured to memory buffer will be rotated.
+
+ +---------------------------------------+
+ | _ _ |
+ | \ / |
+ | | | |
+ | | | |
+ | | > |
+ | < | |
+ | | | |
+ | . |
+ | V |
+ +---------------------------------------+
+
+ A correction of 90 degrees in counterclockwise direction has to be
+ applied to correctly display the image in portrait mode on the device
+ screen.
+
+ +-----------------+
+ | |
+ | |
+ | |
+ | |
+ | |
+ | |
+ | |\____)\___ |
+ | ) _____ __`< |
+ | |/ )/ |
+ | |
+ | |
+ | |
+ | |
+ | |
+ +-----------------+
+...
--
2.24.0
More information about the libcamera-devel
mailing list