Camera Metadata

================================================================================
* Byte Order:

If a field specified in this document has more than one byte width, little
endian format will be used to put the value in the bit stream.

================================================================================
* CSI Line marker and length indicator:

When a CSI line contains valid list of metadata, the line shoud be marked with
special signature (0xAA 0x01) at first 2 byte. Next 2 bytes will indicate total
size of metadata block in the line. See the figure below.

byte    0      1      2      3      4       5
     +------+------+------+------+------+------
line | 0xAA | 0x01 |    length   | metadata ...
     +------+------+------+------+------+------

================================================================================
* Metadata Structure:

Each metadata will have own header in front of the payload. Multiple metadata
shall be concatenated back to back like the figure below.

 +----------+----------+----------+---------+----------+-----
 | metadata | payload  | metadata | payload | metadata |
 |  header  |          |  header  |         |  header  | continues ..
 |   (0)    |   (0)    |   (1)    |   (1)   |   (2)    |
 +----------+----------+----------+---------+----------+-----

================================================================================
* Metadata Fragumentation:

When size of metadata block exceeds the length of active pixels in the CSI line,
metadata shall be split in to pieces. Each line should have valid line marker
described above. The line not containing metadata block shall be have marker
other than "0xAA 0x01".

See figure below for the case of reserving 3 lines for metadata blocks.

           +------+------+------+------+------+------
line x     | 0xAA | 0x01 |    length   | metadata ...
           +------+------+------+------+------+------
line x + 1 | 0xAA | 0x01 |    length   | metadata ...
           +------+------+------+------+------+------
line x + 2 | 0x00 | 0x00 |    unknown content
           +------+------+------+------+------+------

================================================================================
* Metadata header

Metadata header shall consists of "tag" and "payload length". Tag will be
a unique value defined for each metadata. Length is the size of payload
following the metadata header.

             (byte)   0       1         2       3
                 +--------+--------+--------+--------+
                 |       tag       |     payload     |
                 |                 |      length     |
                 +--------+--------+--------+--------+

================================================================================
* Metadata types summary

The following is the list metadata and it's assigned tags.

  Tag: 0  - Auto Focus Status
  Tag: 1  - Zoom Status
  Tag: 2  - Postview frame identification
  Tag: 3  - Xenon Flash
  Tag: 4  - AE Status
  Tag: 5  - Faces
  Tag: 6  - Focus Distances
  Tag: 7  - Capture Image Ack
  Tag: 8  - Image Data Transfer
  Tag: 9  - Mod Status Indication

================================================================================
* "Auto Focus Status" (0x00)

               (byte)   0             1
                 +-------------+-------------+
                 |   Request   |   Status    |
                 |   Complete  |             |
                 +-------------+-------------+

   Request Complet Values:
   0 - not valid
   1 - success
   2 - failure
   3 - finished

   Status Values:
   0 - not valid
   1 - started
   2 - stopped
   3 - updating

================================================================================
* "Zoom Status" (0x01)

  (byte)    0               1            3              4
       +-------------+-------------+-------------+-------------+
       |    Zoom     |  Zoom Value |  Zoom Value |  Reserved   |
       |   Activity  |    Numerator  | Denominator |           |
       +-------------+-------------+-------------+-------------+

   Zoom Activity Values:
   0 - not valid
   1 - moving
   2 - stopped

   Zoom Value :
   Represents current zoon value.

   example - Zoom Numerator = 75, Zoom Denominator = 10
             Current Zoom = 75 / 10 ==> 7.5X

================================================================================
* "Postview Frame Indication" (0x02)

               (byte)   0             1
                 +-------------+-------------+
                 |       Shutter Frame       |
                 |           Marker          |
                 +-------------+-------------+

   Shutter Frame Maker value (N):
   0 .. (greater than zero)
   N indicats N frames earlier of tis frame was the time shutter event was
   triggered. N = 2 means shutter was triggered 2 frames before this frame.

================================================================================
* "Xenon Flash Status" (0x03)

               (byte)   0             1
                 +-------------+-------------+
                 |   Charged   |    Auto     |
                 |             |    Flash    |
                 +-------------+-------------+

   Charged Values:
   0 - not valid
   1 - charged
   2 - not charged

   Auto Flash Values :
   0 - not valid
   1 - Fire the flash if FlashMode is set to "Auto"

================================================================================
* "AE Status" (0x04)

  (byte)    0               1            3              4
       +-------------+-------------+-------------+-------------+
       |                        Exposure                          |
       |                   Time                       |
       +-------------+-------------+-------------+-------------+
       |                        Exposure                       |
       |                          Time                         |
       +-------------+-------------+-------------+-------------+
       |            Lux            |            Lux            |
       |          Numerator        |        Denominator        |
       +-------------+-------------+-------------+-------------+
       |            ISO            |  Aperture   | Aperture    |
       |            Gain           |  Numerator  | Denominator |
       +-------------+-------------+-------------+-------------+

   Exposure Time :
   8 bytes field. Unit is in nano seconds

   Lux Numerator and Denoninator :
   Represents Lux value in float.

   example - Lux Numerator = 125, Denominator = 1000
             Then, Lux = 125 / 1000 = 0.125

   ISO Gain :
   Signed integer. Unit in dBm.

   Aperture Numerator and Denominator :
   Represents f/N value in float.

   example - Aperture Numerator = 22, Denominator = 10
             Then Aperture = 22/10 ==> f/2.2

================================================================================
* "Faces" (0x05)

               (byte)   0             1
                 +-------------+-------------+
                 |            Num            |
                 |           Faces           |
                 +-------------+-------------+
                 |     Id      |     Score   |
                 |             |             |
                 +-------------+-------------+
                 |         Face Bound        |
                 |           bottom          |
                 +-------------+-------------+
                 |         Face Bound        |
                 |           left            |
                 +-------------+-------------+
                 |         Face Bound        |
                 |           right           |
                 +-------------+-------------+
                 |         Face Bound        |
                 |            top            |
                 +-------------+-------------+
                 |         Left Eye          |
                 |             x             |
                 +-------------+-------------+
                 |         Left Eye          |
                 |             y             |
                 +-------------+-------------+
                 |         Right Eye         |
                 |             x             |
                 +-------------+-------------+
                 |         Right Eye         |
                 |             y             |
                 +-------------+-------------+
                 |           Mouth           |
                 |             x             |
                 +-------------+-------------+
                 |           Mouth           |
                 |             y             |
                 +-------------+-------------+
                 |  Repeats for Num Faces    |
                 |           ....            |

   Num Faces :
   Unsigned Integer. Number of Faces in the metadata.

   Id :
   Signed Integer. -1 if Id is not supported.

   Score :
   Range 1 - 100. -1 if Score is not supported.

   Face Bound (bottom, left, right, top) :
   Signed Integer. Must be supported.

   Left Eye Point (x, y) :
   Signed Integer. Set to -1 if not supported.

   Right Eye Point (x, y) :
   Signed Integer. Set to -1 if not supported.

   Mouth Point (x, y) :
   Signed Integer. Set to -1 if not supported.

================================================================================
* "Focus Distances" (0x06)

  (byte)    0               1            3              4
       +-------------+-------------+-------------+-------------+
       |         Near Focus        |         Near Focus        |
       |          Numerator        |        Denominator        |
       +-------------+-------------+-------------+-------------+
       |      Optimal Focus        |      Optimal Focus        |
       |          Numerator        |        Denominator        |
       +-------------+-------------+-------------+-------------+
       |          Far Focus        |          Far Focus        |
       |          Numerator        |        Denominator        |
       +-------------+-------------+-------------+-------------+

   Focus Distance Numerator and Denoninator :
   Optimal Focus Distance is the distance with sharpest image. The subject
   distance may be within near and far focus distance.

   Unit in meters.

   Numerator=65535 or Denominator=0 signifies infinite focus

   example - Focus Distance Numerator = 155, Denominator = 10
             Then, Focus Distance = 15.5 meters

================================================================================
* "Capture Image Ack" (0x07)

               (byte)   0             1
                 +-------------+-------------+
                 |   Status    |   Reserved  |
                 |             |             |
                 +-------------+-------------+

   Status Values:
   0 - Idle
   1 - Ack

   Normally the Status will always be set to "Idle" (0) for all metadata
   frames during preview operation.  When a CAPTURE_IMAGE request is made,
   the Status will change to "Ack" (1) for a single metadata frame to
   acknowledge receipt of the request, then restore back to "Idle" (0).

================================================================================
* "Image Data Transfer" (0x08)

               (byte)   0             1
                 +-------------+-------------+
                 |   Status    |   Image     |
                 |             |   Type      |
                 +-------------+-------------+

   Status Values:
   0 - Idle
   1 - Transferring
   2 - Completed Transfer

   Image Type Values:
   0 - None
   1 - JPEG
   2 - DNG

   Normally the Status will be "Idle" (0) and Image Type "None" (0) for all
   metadata frames during preview operation.  When a UVC transfer begins,
   the Status will transition to "Transferring" (1) while the image is
   being transferred.  After UVC transfer completes, the Status will indicate
   "Completed Transfer" (2) for a single metadata frame, then restore back
   to "Idle" (0).

   Example Status sequence:  ... 0, 0, 0, 0, 1, 1, 1, 1, 1, 2, 0, 0, 0, 0, ...

   If the transfer is for a small image which takes <33ms transfer latency,
   only the Status "Completed Transfer" (2) will be sent in a single metadata
   frame, then restore back to "Idle" (0).

   Example Status sequence:  ... 0, 0, 0, 0, 2, 0, 0, 0, 0, ...

   The "Image Type" will always reflect what is being transferred.

================================================================================
* "Mod Status Indication" (0x09)

               (byte)   0             1
                 +-------------+-------------+
                 |   Error     |   Status    |
                 |   Flag      |   Code      |
                 +-------------+-------------+

   Error Flag:                         
   0 - No Error
   1 - Fatal - Require Camera to stop
   2 - Critical - Require Streams to be restarted

   Status Code:
   Mods dependent. Used for logging purpose only

   Used for indicate status of Camera Mod in supplementary to greybys Camera-Ext
   protocol. Providing an alternate way to provide the status of Mod in detail.
   Also Error Flag can be used to communicate error to the phone if necessary.

================================================================================