[libcamera-devel] [PATCH v2 1/7] libcamera: properties: Define pixel array properties

[Jacopo Mondi]

Add definition of pixel array related properties.

Signed-off-by: Jacopo Mondi <jacopo at jmondi.org>
---
 src/libcamera/property_ids.yaml | 177 ++++++++++++++++++++++++++++++++
 1 file changed, 177 insertions(+)

diff --git a/src/libcamera/property_ids.yaml b/src/libcamera/property_ids.yaml
index c3070de9d9f8..709016904870 100644
--- a/src/libcamera/property_ids.yaml
+++ b/src/libcamera/property_ids.yaml
@@ -354,4 +354,181 @@ controls:
                                 |               |
                                 |               |
                                 +---------------+
+
+  - PixelArraySize:
+      type: float
+      compound: true
+      description: |
+        The physical sizes of the pixel array (width and height), in
+        millimeters.
+
+  - PixelArrayBounds:
+      type: int32_t
+      compound: true
+      description: |
+        The camera sensor pixel array bounding rectangle vertical and
+        horizontal sizes.
+
+        For image sensors with a rectangular pixel array the sizes described by
+        this property are the same as the PixelAreaSize property size.
+
+        For image sensors with more complex pixel array displacements (such as
+        cross-shaped pixel arrays, non symmetrical pixel arrays etc) this
+        property represents the bounding rectangle in which all pixel array
+        dimensions are inscribed into.
+
+        In example, the bounding rectangle sizes for image sensor with a
+        cross-shaped pixel array is described as
+
+
+                     PixelArrayBound(0) = width
+                    /-----------------/
+
+            (0,0)-> +----+------+----+  /
+                    |    |//////|    |  |
+                    +----+//////+----+  |
+                    |////////////////|  | PixelArrayBound(1) = height
+                    +----+//////+----+  |
+                    |    |//////|    |  |
+                    +----+------+----+  /
+                            |
+                             -> Cross-shaped pixel area
+
+  - PixelArrays:
+      type: int32_t
+      compound: true
+      description: |
+        The sensor pixel array rectangles, relative to the rectangle described
+        by the PixelArrayBounds property.
+
+        This property describes an arbitrary number of (likely overlapping)
+        rectangles, representing the pixel array areas the sensor is composed
+        of.
+
+        Each rectangle is defined by its displacement from pixel (0, 0) of
+        the bounding rectangle described by the PixelArrayBound property.
+
+        For image sensors with a rectangular pixel array, a single rectangle
+        is required. For sensors with more complex pixel array displacements
+        multiple rectangles shall be specified, ordered from the tallest to the
+        shorter one.
+
+        For each rectangle, this property reports the full pixel array size,
+        including non-active pixels, black level calibration pixels etc.
+
+        In example, a simple sensor with a rectangular pixel array is described
+        as
+
+                     PixelArrayBound(0) = width
+                    /-----------------/
+                      x1          x2
+            (0,0)-> +-o------------o-+  /
+                 y1 o +------------+ |  |
+                    | |////////////| |  |
+                    | |////////////| |  | PixelArrayBound(1) = height
+                    | |////////////| |  |
+                 y2 o +------------+ |  |
+                    +----------------+  /
+
+                 PixelArray = (x1, y1, (x2 - x1), (y2 - y1))
+
+        A more complex sensor, with a cross shaped pixel array displacement
+        is described with 2 rectangles, with the vertical rectangle
+        described first
+
+                     PixelArrayBound(0) = width
+                    /-----------------/
+                    x1  x2     x3  x4 W
+            (0,0)-> +o---o------o---o+  /
+                    |    |//////|    |  |
+                 y1 o+---+------+---+|  |
+                    ||///|//////|///||  | PixelArrayBound(1) = height
+                 y2 o+---+------+---+|  |
+                    |    |//////|    |  |
+                 H  +----+------+----+  /
+
+
+                PixelArray = ( (x2, 0, (x3 - x2), H),
+                               (x1, y1, (x4 - x1), (y2 - y1))
+
+  - ActiveAreaSize:
+      type: int32_t
+      compound: true
+      description: |
+        The sensor active pixel area sizes, represented as rectangles
+        inscribed in the ones described by the PixelArrays property.
+
+        One ActiveAreaSize rectangle per each rectangle described in the
+        PixelArrays property is required. As a consequence, the two properties
+        shall transport the same number of elements.
+
+        The ActiveAreaSize rectangles represent the maximum image sizes the
+        sensor can produce.
+
+  - BayerFilterArrangement:
+      type: int32_t
+      description: |
+        The pixel array color filter displacement.
+
+        This property describes the arrangement and readout sequence of the
+        three RGB color components of the sensor's Bayer Color Filter Array
+        (CFA).
+
+        Color filters are usually displaced in line-alternating fashion on the
+        sensor pixel array. In example, one line might be composed of Red-Green
+        while the successive is composed of Blue-Green color information.
+
+        The value of this property represent the arrangement of color filters
+        in the top-left 2x2 pixel square.
+
+        In example, for a sensor with the following color filter displacement
+
+                 (0, 0)               (max-col)
+           +---+    +--------------...---+
+           |B|G|<---|B|G|B|G|B|G|B|...B|G|
+           |G|R|<---|G|R|G|R|G|R|G|...G|R|
+           +---+    |B|G|B|G|B|G|B|...B|G|
+                    ...                  ..
+                    ...                  ..
+                    |G|R|G|R|G|R|G|...G|R|
+                    |B|G|B|G|B|G|B|...B|G|   (max-lines)
+                    +--------------...---+
+
+        The filer arrangement is represented by the BGGR value, which correspond
+        to the pixel readout sequence in line interleaved mode.
+
+      enum:
+        - BayerFilterRGGB:
+            value: 0
+            description: |
+              Color filter array displacement is Red-Green/Green-Blue
+
+        - BayerFilterGRBG:
+            value: 1
+            description: |
+              Color filter array displacement is Green-Red/Blue-Green
+
+        - BayerFilterGBRG:
+            value: 2
+            description: |
+              Color filter array displacement is Green-Blue/Red-Green
+
+        - BayerFilterBGGR:
+            value: 3
+            description: |
+              Color filter array displacement is Blue-Green/Green-Red
+
+        - BayerFilterNonStandard:
+            value: 4
+            description: |
+              The pixel array color filter does not use the standard Bayer RGB
+              color model
+
+  - ISOSensitivityRange:
+      type: int32_t
+      compound: true
+      description: |
+        The range of supported ISO sensitivities, as documented by the
+        ISO 12232:2006 standard
+
 ...
-- 
2.24.1