GNU Linux-libre 4.14.295-gnu1
[releases.git] / Documentation / media / uapi / v4l / pixfmt-meta-vsp1-hgt.rst
1 .. -*- coding: utf-8; mode: rst -*-
2
3 .. _v4l2-meta-fmt-vsp1-hgt:
4
5 *******************************
6 V4L2_META_FMT_VSP1_HGT ('VSPT')
7 *******************************
8
9 Renesas R-Car VSP1 2-D Histogram Data
10
11
12 Description
13 ===========
14
15 This format describes histogram data generated by the Renesas R-Car VSP1
16 2-D Histogram (HGT) engine.
17
18 The VSP1 HGT is a histogram computation engine that operates on HSV
19 data. It operates on a possibly cropped and subsampled input image and
20 computes the sum, maximum and minimum of the S component as well as a
21 weighted frequency histogram based on the H and S components.
22
23 The histogram is a matrix of 6 Hue and 32 Saturation buckets, 192 in
24 total. Each HSV value is added to one or more buckets with a weight
25 between 1 and 16 depending on the Hue areas configuration. Finding the
26 corresponding buckets is done by inspecting the H and S value independently.
27
28 The Saturation position **n** (0 - 31) of the bucket in the matrix is
29 found by the expression:
30
31     n = S / 8
32
33 The Hue position **m** (0 - 5) of the bucket in the matrix depends on
34 how the HGT Hue areas are configured. There are 6 user configurable Hue
35 Areas which can be configured to cover overlapping Hue values:
36
37 ::
38
39          Area 0       Area 1       Area 2       Area 3       Area 4       Area 5
40         ________     ________     ________     ________     ________     ________
41    \   /|      |\   /|      |\   /|      |\   /|      |\   /|      |\   /|      |\   /
42     \ / |      | \ / |      | \ / |      | \ / |      | \ / |      | \ / |      | \ /
43      X  |      |  X  |      |  X  |      |  X  |      |  X  |      |  X  |      |  X
44     / \ |      | / \ |      | / \ |      | / \ |      | / \ |      | / \ |      | / \
45    /   \|      |/   \|      |/   \|      |/   \|      |/   \|      |/   \|      |/   \
46   5U   0L      0U   1L      1U   2L      2U   3L      3U   4L      4U   5L      5U   0L
47         <0..............................Hue Value............................255>
48
49 When two consecutive areas don't overlap (n+1L is equal to nU) the boundary
50 value is considered as part of the lower area.
51
52 Pixels with a hue value included in the centre of an area (between nL and nU
53 included) are attributed to that single area and given a weight of 16. Pixels
54 with a hue value included in the overlapping region between two areas (between
55 n+1L and nU excluded) are attributed to both areas and given a weight for each
56 of these areas proportional to their position along the diagonal lines
57 (rounded down).
58
59 The Hue area setup must match one of the following constrains:
60
61 ::
62
63     0L <= 0U <= 1L <= 1U <= 2L <= 2U <= 3L <= 3U <= 4L <= 4U <= 5L <= 5U
64
65 ::
66
67     0U <= 1L <= 1U <= 2L <= 2U <= 3L <= 3U <= 4L <= 4U <= 5L <= 5U <= 0L
68
69 **Byte Order.**
70 All data is stored in memory in little endian format. Each cell in the tables
71 contains one byte.
72
73 .. flat-table:: VSP1 HGT Data - (776 bytes)
74     :header-rows:  2
75     :stub-columns: 0
76
77     * - Offset
78       - :cspan:`4` Memory
79     * -
80       - [31:24]
81       - [23:16]
82       - [15:8]
83       - [7:0]
84     * - 0
85       - -
86       - S max [7:0]
87       - -
88       - S min [7:0]
89     * - 4
90       - :cspan:`4` S sum [31:0]
91     * - 8
92       - :cspan:`4` Histogram bucket (m=0, n=0) [31:0]
93     * - 12
94       - :cspan:`4` Histogram bucket (m=0, n=1) [31:0]
95     * -
96       - :cspan:`4` ...
97     * - 132
98       - :cspan:`4` Histogram bucket (m=0, n=31) [31:0]
99     * - 136
100       - :cspan:`4` Histogram bucket (m=1, n=0) [31:0]
101     * -
102       - :cspan:`4` ...
103     * - 264
104       - :cspan:`4` Histogram bucket (m=2, n=0) [31:0]
105     * -
106       - :cspan:`4` ...
107     * - 392
108       - :cspan:`4` Histogram bucket (m=3, n=0) [31:0]
109     * -
110       - :cspan:`4` ...
111     * - 520
112       - :cspan:`4` Histogram bucket (m=4, n=0) [31:0]
113     * -
114       - :cspan:`4` ...
115     * - 648
116       - :cspan:`4` Histogram bucket (m=5, n=0) [31:0]
117     * -
118       - :cspan:`4` ...
119     * - 772
120       - :cspan:`4` Histogram bucket (m=5, n=31) [31:0]