| @@ -0,0 +1,51 @@ |
| 1 | +.. -*- coding: utf-8; mode: rst -*- |
| 2 | + |
| 3 | +.. _v4l2-meta-fmt-uvc: |
| 4 | + |
| 5 | +******************************* |
| 6 | +V4L2_META_FMT_UVC ('UVCH') |
| 7 | +******************************* |
| 8 | + |
| 9 | +UVC Payload Header Data |
| 10 | + |
| 11 | + |
| 12 | +Description |
| 13 | +=========== |
| 14 | + |
| 15 | +This format describes standard UVC metadata, extracted from UVC packet headers |
| 16 | +and provided by the UVC driver through metadata video nodes. That data includes |
| 17 | +exact copies of the standard part of UVC Payload Header contents and auxiliary |
| 18 | +timing information, required for precise interpretation of timestamps, contained |
| 19 | +in those headers. See section "2.4.3.3 Video and Still Image Payload Headers" of |
| 20 | +the "UVC 1.5 Class specification" for details. |
| 21 | + |
| 22 | +Each UVC payload header can be between 2 and 12 bytes large. Buffers can |
| 23 | +contain multiple headers, if multiple such headers have been transmitted by the |
| 24 | +camera for the respective frame. However, the driver may drop headers when the |
| 25 | +buffer is full, when they contain no useful information (e.g. those without the |
| 26 | +SCR field or with that field identical to the previous header), or generally to |
| 27 | +perform rate limiting when the device sends a large number of headers. |
| 28 | + |
| 29 | +Each individual block contains the following fields: |
| 30 | + |
| 31 | +.. flat-table:: UVC Metadata Block |
| 32 | + :widths: 1 4 |
| 33 | + :header-rows: 1 |
| 34 | + :stub-columns: 0 |
| 35 | + |
| 36 | + * - Field |
| 37 | + - Description |
| 38 | + * - __u64 ts; |
| 39 | + - system timestamp in host byte order, measured by the driver upon |
| 40 | + reception of the payload |
| 41 | + * - __u16 sof; |
| 42 | + - USB Frame Number in host byte order, also obtained by the driver as |
| 43 | + close as possible to the above timestamp to enable correlation between |
| 44 | + them |
| 45 | + * - :cspan:`1` *The rest is an exact copy of the UVC payload header:* |
| 46 | + * - __u8 length; |
| 47 | + - length of the rest of the block, including this field |
| 48 | + * - __u8 flags; |
| 49 | + - Flags, indicating presence of other standard UVC fields |
| 50 | + * - __u8 buf[]; |
| 51 | + - The rest of the header, possibly including UVC PTS and SCR fields |