Argus API
Argus Camera API
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
CaptureMetadata.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2016, 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 #ifndef _ARGUS_CAPTURE_METADATA_H
30 #define _ARGUS_CAPTURE_METADATA_H
31 
32 
33 namespace Argus
34 {
35 
36 /**
37  * A container for metadata from a single capture.
38  */
40 {
41 protected:
43 };
44 
45 /**
46  * An object that holds a CaptureMetadata instance
47  * and is used to read the capture metadata from a consumer thread directly from
48  * the embedded EGLStream metadata. It exposes the same interfaces as
49  * CaptureMetadata, but is owned by the consumer.
50  */
52 {
53 protected:
55 };
56 
57 
58 /**
59  * @class IBayerHistogram
60  *
61  * An interface to a set of histograms created from Bayer pixel data, one per Bayer channel.
62  * Bins are evenly distributed across the possible range of values,
63  * and each contains the number of pixels whose value fell within the range for that bin.
64  */
65 DEFINE_UUID(InterfaceID, IID_BAYER_HISTOGRAM, 50bc4f1c,6424,beb7,baae,b0,90,c9,c3,25,9e);
66 
67 class IBayerHistogram : public Interface
68 {
69 public:
70 
71  static const InterfaceID& id() { return IID_BAYER_HISTOGRAM; }
72 
73  /**
74  * Returns the number of bins (per channel) in the histogram.
75  */
76  virtual uint32_t getBinCount() const = 0;
77 
78  /**
79  * Returns the value contained in a single bin.
80  * @returns 0 if <tt>bin >= getBinCount()</tt>;
81  * if @c status is non-NULL, STATUS_INVALID_PARAMS will be returned there.
82  */
83  virtual uint32_t getBinData(BayerChannel channel, uint32_t bin,
84  Status* status = NULL) const = 0;
85 
86 protected:
87 
89 };
90 
91 
92 /**
93  * @class IRGBHistogram
94  *
95  * An interface to a set of histograms created from RGB pixel data, one per RGB channel.
96  * Bins are evenly distributed across the possible range of values,
97  * and each contains the number of pixels whose value fell within the range for that bin.
98  */
99  DEFINE_UUID(InterfaceID, IID_RGB_HISTOGRAM, 50bc4f1d,6424,beb7,baae,b0,90,c9,c3,25,9e);
100 
101 class IRGBHistogram : public Interface
102 {
103 public:
104 
105  static const InterfaceID& id() { return IID_RGB_HISTOGRAM; }
106 
107  /**
108  * Returns the number of bins (per channel) in the histogram.
109  */
110  virtual uint32_t getBinCount() const = 0;
111 
112  /**
113  * Returns the value contained in a single bin.
114  * @returns 0 if <tt>bin >= getBinCount()</tt>;
115  * if @c status is non-NULL, STATUS_INVALID_PARAMS will be returned there.
116  */
117  virtual uint32_t getBinData(RGBColorChannel channel, uint32_t bin,
118  Status* status = NULL) const = 0;
119 
120 protected:
121 
123 };
124 
125 
126 /**
127  * @class IStreamCaptureMetadata
128  *
129  * An interface that reports metadata for a single stream in a single capture.
130  */
131 DEFINE_UUID(InterfaceID, IID_STREAM_CAPTURE_METADATA, 61cbe0a8,0ee1,4c67,baae,02,02,1a,b8,d9,47);
132 
134 {
135 public:
136 
137  static const InterfaceID& id() { return IID_STREAM_CAPTURE_METADATA; }
138 
139  /**
140  * Returns the clip rectangle used for this stream.
141  */
142  virtual NormalizedRect getSourceClipRect() const = 0;
143 
144 protected:
145 
147 };
148 
149 
150 /**
151  * @class ICaptureMetadata
152  *
153  * An interface that reports metadata for a single capture.
154  */
155 DEFINE_UUID(InterfaceID, IID_CAPTURE_METADATA, 5f6ac5d4,59e8,45d0,8bac,38,09,1f,f8,74,a9);
156 
158 {
159 public:
160 
161  static const InterfaceID& id() { return IID_CAPTURE_METADATA; }
162 
163  static const uint32_t NUM_COLOR_CORRECTION_ELEMENTS = 9;
164  static const uint32_t NUM_AWB_WB_ESTIMATE_ELEMENTS = 4;
165 
166  /**
167  * Returns the capture id (the value returned from ICaptureSession::capture())
168  * of the capture that generated this metadata.
169  */
170  virtual uint32_t getCaptureId() const = 0;
171 
172  /**
173  * Returns the @c clientData value for the Request used in the capture
174  * that generated this metadata.
175  *
176  * @see ICaptureSession::createRequest()
177  */
178  virtual uint32_t getClientData() const = 0;
179 
180  /**
181  * Returns the per-stream metadata provider for @c stream.
182  * This object will provide the IStreamCaptureMetadata interface.
183  */
184  virtual InterfaceProvider* getStreamMetadata(const OutputStream* stream) const = 0;
185 
186  /**
187  * Returns the Bayer histogram for this capture.
188  * This object will provide the IBayerHistogram interface.
189  */
190  virtual const InterfaceProvider* getBayerHistogram() const = 0;
191 
192  /**
193  * Returns the RGB histogram for this capture.
194  * This object will provide the IRGBHistogram interface.
195  */
196  virtual const InterfaceProvider* getRGBHistogram() const = 0;
197 
198  /**
199  * Returns true if and only if AE was locked for this capture.
200  */
201  virtual bool getAeLocked() const = 0;
202 
203  /**
204  * Gets the AE regions of interest used for this capture.
205  *
206  * @param[in] regions A vector that will be populated with the AE regions used in capture.
207  *
208  * @returns success/status of the call.
209  */
210  virtual Status getAeRegions(std::vector<AcRegion>* regions) const = 0;
211 
212  /**
213  * Returns the state of AE when it ran for this capture.
214  */
215  virtual AeState getAeState() const = 0;
216 
217  /**
218  * Returns the focuser position used for this capture (in focuser steps).
219  */
220  virtual int32_t getFocuserPosition() const = 0;
221 
222  /**
223  * Returns the CCT calculated by AWB for this capture.
224  */
225  virtual uint32_t getAwbCct() const = 0;
226 
227  /**
228  * Returns the AWB gains used for this capture.
229  */
230  virtual BayerTuple<float> getAwbGains() const = 0;
231 
232  /**
233  * Returns the AWB mode used for this capture.
234  */
235  virtual AwbMode getAwbMode() const = 0;
236 
237  /**
238  * Gets the AWB regions of interest used for this capture.
239  *
240  * @param[in] regions A vector that will be populated with the AWB regions used in capture.
241  *
242  * @returns success/status of the call.
243  */
244  virtual Status getAwbRegions(std::vector<AcRegion>* regions) const = 0;
245 
246  /**
247  * @returns the state of AWB when it ran for this capture.
248  */
249  virtual AwbState getAwbState() const = 0;
250 
251  /**
252  * Gets the current AWB WB estimate as a vector of NUM_AWB_WB_ESTIMATE_ELEMENTS values.
253  * @todo DOC describe getAwbWbEstimate() really.
254  *
255  * @param[in] estimate A vector that will be populated with the AWB WB estimates.
256  *
257  * @returns success/status of the call.
258  */
259  virtual Status getAwbWbEstimate(std::vector<float>* estimate) const = 0;
260 
261  /**
262  * Returns the enable state for the client-supplied Color Correction Matrix.
263  */
264  virtual bool getColorCorrectionMatrixEnable() const = 0;
265 
266  /**
267  * Gets the 3x3 client-supplied Color Correction Matrix as a flattened
268  * (row-major) vector of 9 values. This matrix is irrelevant if
269  * <tt>getColorCorrectionMatrixEnable() == false</tt>.
270  *
271  * @param[in] ccMatrix A vector that will be populated with the color correction matrix.
272  *
273  * @returns success/status of the call.
274  */
275  virtual Status getColorCorrectionMatrix(std::vector<float>* ccMatrix) const = 0;
276 
277  /**
278  * Returns the color saturation value used for this capture (including biasing).
279  */
280  virtual float getColorSaturation() const = 0;
281 
282  /**
283  * Returns the time it took to integrate this capture (in nanoseconds).
284  * @todo DOC a more precise description
285  */
286  virtual uint64_t getFrameDuration() const = 0;
287 
288  /**
289  * Returns the digital gain used for this capture.
290  */
291  virtual float getIspDigitalGain() const = 0;
292 
293  /**
294  * Returns the frame readout time for this capture (in nanoseconds) from
295  * the beginning of the first line to the beginning of the last line.
296  */
297  virtual uint64_t getFrameReadoutTime() const = 0;
298 
299  /**
300  * Returns the estimated scene brightness for this capture (in lux).
301  */
302  virtual float getSceneLux() const = 0;
303 
304  /**
305  * Returns the sensor analog gain used for this capture.
306  */
307  virtual float getSensorAnalogGain() const = 0;
308 
309  /**
310  * Returns the sensor exposure time for this capture (in nanoseconds).
311  */
312  virtual uint64_t getSensorExposureTime() const = 0;
313 
314  /**
315  * Returns the ISO value used for this capture.
316  */
317  virtual uint32_t getSensorSensitivity() const = 0;
318 
319  /**
320  * Returns the start timestamp for the sensor (in nanoseconds).
321  * This is the time that the first data from this capture arrives from the sensor.
322  */
323  virtual uint64_t getSensorTimestamp() const = 0;
324 
325  /**
326  * Returns true if and only if a user-specified tone map curve was used for this capture.
327  */
328  virtual bool getToneMapCurveEnabled() const = 0;
329 
330  /**
331  * Returns the specified color channel for the tone mapping table
332  * (as a vector of NUM_TONE_MAP_ELEMENTS values). These values are irrelevant if
333  * <tt>getToneMapCurveEnabled() == false</tt>.
334  *
335  * @param[in] channel Specified the color channel for which the curve will be returned.
336  * @param[in] curve A vector that will be populated with the color curve used in capture.
337  *
338  * @returns success/status of the call.
339  */
340  virtual Status getToneMapCurve(RGBColorChannel channel, std::vector<float>* curve) const = 0;
341 
342 protected:
344 };
345 
346 /**
347  * @class IDenoiseMetadata
348  * - Exposed by CaptureMetadata objects.
349  */
350 DEFINE_UUID(InterfaceID, IID_DENOISE_METADATA, 7A461D23,6AE1,11E6,BDF4,08,00,20,0C,9A,66);
351 
353 {
354 public:
355  static const InterfaceID& id() { return IID_DENOISE_METADATA; }
356 
357  /**
358  * Returns the denoise mode used for the capture.
359  */
360  virtual DenoiseMode getDenoiseMode() const = 0;
361 
362  /**
363  * Returns the denoise strength used for the capture.
364  */
365  virtual float getDenoiseStrength() const = 0;
366 
367 protected:
369 };
370 
371 /**
372  * @class IEdgeEnhanceMetadata
373  * - Exposed by CaptureMetadata objects.
374  */
375 DEFINE_UUID(InterfaceID, IID_EDGE_ENHANCE_METADATA, 7A461D24,6AE1,11E6,BDF4,08,00,20,0C,9A,66);
376 
378 {
379 public:
380  static const InterfaceID& id() { return IID_EDGE_ENHANCE_METADATA; }
381 
382  /**
383  * Returns the edge enhancement mode used for the capture.
384  */
385  virtual EdgeEnhanceMode getEdgeEnhanceMode() const = 0;
386 
387  /**
388  * Returns the edge enhancement strength used for the capture.
389  */
390  virtual float getEdgeEnhanceStrength() const = 0;
391 
392 protected:
394 };
395 
396 /**
397  * @class IVideoStabilizationMetadata
398  * - Exposed by CaptureMetadata objects.
399  */
400 DEFINE_UUID(InterfaceID, IID_VIDEO_STABILIZATION_METADATA, 7A461D25,6AE1,11E6,BDF4,08,00,20,0C,9A,66);
401 
403 {
404 public:
405  static const InterfaceID& id() { return IID_VIDEO_STABILIZATION_METADATA; }
406 
407  /**
408  * Returns the video stabilization mode used for the capture.
409  */
410  virtual VideoStabilizationMode getVideoStabilizationMode() const = 0;
411 
412 protected:
414 };
415 
416 } // namespace Argus
417 
418 #endif // _ARGUS_CAPTURE_METADATA_H