Libargus API Libargus Camera API

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- File List
- File Members

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);
130 class IDolWdrSensorMode : public Interface
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 */
155 virtual Status getVerticalBlankPeriodRowCount(
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:
184 ~IDolWdrSensorMode() {}
185 };
186
187 } // namespace Ext
188
189 } // namespace Argus
190
191 #endif // _ARGUS_EXT_DOL_WDR_SENSOR_MODE_H