Libargus API
Libargus Camera API
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
DolWdrSensorMode.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2017, NVIDIA CORPORATION. All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  * * Redistributions of source code must retain the above copyright
8  * notice, this list of conditions and the following disclaimer.
9  * * Redistributions in binary form must reproduce the above copyright
10  * notice, this list of conditions and the following disclaimer in the
11  * documentation and/or other materials provided with the distribution.
12  * * Neither the name of NVIDIA CORPORATION nor the names of its
13  * contributors may be used to endorse or promote products derived
14  * from this software without specific prior written permission.
15  *
16  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY
17  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
19  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
20  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
21  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
22  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
23  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
24  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
26  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27  */
28 
29 /**
30  * @file
31  * <b>Libargus Extension: Digital Overlap WDR Sensor Modes</b>
32  *
33  * @b Description: Adds extra functionalities for the
34  * Digital Overlap (DOL) Wide Dynamic Range (WDR) sensor mode type.
35  */
36 
37 #ifndef _ARGUS_EXT_DOL_WDR_SENSOR_MODE_H
38 #define _ARGUS_EXT_DOL_WDR_SENSOR_MODE_H
39 
40 namespace Argus
41 {
42 
43 /**
44  * Adds extra functionalities for the Digital Overlap (DOL) Wide Dynamic
45  * Range (WDR) sensor mode type. It introduces one new interface:
46  * - IDolWdrSensorMode; Returns the extended properties specific to a Digital Overlap (DOL)
47  * Wide Dynamic Range (WDR) extended sensor mode. DOL WDR is a
48  * multi-exposure technology that enables fusion of various exposures
49  * from a single frame to produce a WDR image.
50  *
51  * @defgroup ArgusExtDolWdrSensorMode Ext::DolWdrSensorMode
52  * @ingroup ArgusExtensions
53  */
54 DEFINE_UUID(ExtensionName, EXT_DOL_WDR_SENSOR_MODE, 569fb210,70d9,11e7,9598,08,00,20,0c,9a,66);
55 
56 namespace Ext
57 {
58 
59 /**
60  * @class IDolWdrSensorMode
61  *
62  * Interface to the properties of a DOL WDR device.
63  *
64  * Returns the extended properties specific to a Digital Overlap (DOL)
65  * Wide Dynamic Range (WDR) extended sensor mode. DOL WDR is a multi-exposure technology
66  * that enables fusion of various exposures from a single frame to produce a WDR image.
67  *
68  * A DOL WDR RAW buffer contains different DOL exposures in an interleaved layout. DOL WDR
69  * supports two exposure (long and short) and three exposure (long, short and very short) schemes.
70  * These schemes are referred to as DOL-2 and DOL-3 respectively.
71  *
72  * Exposures are time staggered which leads to vertical blank period (VBP) rows being inserted
73  * in between various exposures. This scheme results in (N-1) sections of VBP rows for an N exposure
74  * DOL WDR frame.
75  *
76  * Each exposure is preceded by optical black (OB) rows.
77  *
78  * Each row of DOL WDR RAW interleaved frame starts with a few Line Info (LI) marker pixels.
79  * LI pixels distinguish the kind of row.
80  * Row types include:
81  * a. Long Exposure
82  * b. Short Exposure
83  * c. Very Short Exposure
84  * d. Vertical Blank Period
85  *
86  * For a DOL-2 exposure scheme, there is only one section of VBP rows. The data layout per exposure
87  * looks like this:
88  * Long exposure has OB rows, image rows, VBP rows.
89  * Short exposure has OB rows, VBP rows, image rows.
90  *
91  * The ordering of VBP rows changes across exposures but the count of VBP rows per exposure
92  * remains the same. The final interleaved DOL WDR RAW frame buffer is produced by interleaving
93  * each exposure's data on a per row basis in a round robin fashion across exposures.
94  *
95  * For a DOL-3 exposure scheme, there are two sections of VBP rows. For the sake of terminology
96  * these are referred to as VBP[0] and VBP[1]. The data layout per exposure looks like this:
97  * Long exposure has OB rows, image rows, VBP[0] rows, VBP[1] rows.
98  * Short exposure has OB rows, VBP[0] rows, image rows, VBP[1] rows.
99  * Very Short exposure has OB rows, VBP[0] rows, VBP[1] rows, image rows.
100  *
101  * Again, only the ordering of VBP[0] and VBP[1] rows changes across exposures but the count of
102  * VBP[0] and VBP[1] rows remains the same. Similar to the DOL-2 scheme, the final interleaved
103  * DOL WDR RAW frame buffer for DOL-3 scheme is produced by interleaving each exposure's data
104  * on a per row basis in a round robin fashion across exposures.
105  *
106  * This scheme can be extended to DOL-N exposures with (N-1) sections of VBP rows ranging from
107  * VBP[0] to VBP[N-2]. When considering the vertical blank period sections for exposure N,
108  * the rows of VBP[X] will come before the image data if X < N, otherwise they will come
109  * after the image data.
110  *
111  * Hence, a DOL-N RAW buffer would have different dimensions than the fused output
112  * WDR frame buffer. The resolution of the DOL-N RAW buffer is referred to as physical resolution.
113  *
114  * The set of properties for basic sensor modes is still applicable to DOL WDR sensor mode. Those
115  * properties are available through the ISensorMode interface. The only difference is that the
116  * resolution property provided by the ISensorMode interface for DOL WDR would be the size of the
117  * fused WDR frame. WDR fusion typically eliminates LI markers, OB rows and VBP rows and merges the
118  * individual exposures to create a frame that is smaller in height and width than the
119  * DOL WDR RAW interleaved frame.
120  *
121  * Following the LI marker pixels is the actual pixel data for each row. This data may include
122  * margin pixels on the left or right side of the row, which are generally used for filtering
123  * and cropped out of a fused DOL image. The width of these margin pixels can be queried by
124  * getLeftMarginWidth()/getRightMarginWidth().
125  * @see ISensorMode
126  *
127  * @ingroup ArgusSensorMode ArgusExtDolWdrSensorMode
128  */
129 DEFINE_UUID(InterfaceID, IID_DOL_WDR_SENSOR_MODE, a1f4cae0,70dc,11e7,9598,08,00,20,0c,9a,66);
131 {
132 public:
133  static const InterfaceID& id() { return IID_DOL_WDR_SENSOR_MODE; }
134 
135  /**
136  * Returns the number of exposures captured per frame for this DOL WDR mode.
137  * Typically, 2 = Long, Short or 3 = Long, Short, Very Short exposures.
138  */
139  virtual uint32_t getExposureCount() const = 0;
140 
141  /**
142  * Returns number of Optical Black rows at the start of each exposure in a DOL WDR frame.
143  */
144  virtual uint32_t getOpticalBlackRowCount() const = 0;
145 
146  /**
147  * Returns number of vertical blank period rows for each DOL WDR exposure.
148  *
149  * @param[out] verticalBlankPeriodRowCounts The output vector to store the
150  * vertical blank period (VBP) rows per DOL WDR exposure. Size of the vector is
151  * getExposureCount()-1 count values. When considering the vertical blank period
152  * sections for exposure N, the rows of VBP[X] will come before the image data
153  * if X < N, otherwise they will come after the image data.
154  */
156  std::vector<uint32_t>* verticalBlankPeriodRowCounts) const = 0;
157 
158  /**
159  * Returns line info markers width in pixels.
160  * These occur at the start of each pixel row to distinguish row types. There are different
161  * line info markers to distinguish each different exposure and vertical blank period rows.
162  *
163  * Optical black rows have the same line info markers as the exposure type they appear on.
164  */
165  virtual uint32_t getLineInfoMarkerWidth() const = 0;
166 
167  /**
168  * Returns number of margin pixels on left per row.
169  */
170  virtual uint32_t getLeftMarginWidth() const = 0;
171 
172  /**
173  * Returns number of margin pixels on right per row.
174  */
175  virtual uint32_t getRightMarginWidth() const = 0;
176 
177  /**
178  * Returns the physical resolution derived due to the interleaved exposure output from DOL WDR
179  * frames.
180  */
181  virtual Size2D<uint32_t> getPhysicalResolution() const = 0;
182 
183 protected:
185 };
186 
187 } // namespace Ext
188 
189 } // namespace Argus
190 
191 #endif // _ARGUS_EXT_DOL_WDR_SENSOR_MODE_H