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
Settings.h
Go to the documentation of this file.
1 /*
2 * Copyright (c) 2016-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 API: Settings API</b>
32 *
33 * @b Description: This file defines the settings that control the sensor module.
34 */
35
36 #ifndef _ARGUS_SETTINGS_H
37 #define _ARGUS_SETTINGS_H
38
39 namespace Argus
40 {
41
42 /**
43 * @class ISourceSettings
44 *
45 * Interface to the source settings (provided by IRequest::getSourceSettings()).
46 *
47 * @ingroup ArgusSourceSettings
48 */
49 DEFINE_UUID(InterfaceID, IID_SOURCE_SETTINGS, eb7ae38c,3c62,4161,a92a,a6,4f,ba,c6,38,83);
50 class ISourceSettings : public Interface
51 {
52 public:
53 static const InterfaceID& id() { return IID_SOURCE_SETTINGS; }
54
55 /**
56 * Sets the exposure time range of the source, in nanoseconds.
57 * If the exposure range is outside of the available range, the capture's exposure time
58 * will be as close as possible to the exposure range specified.
59 * @param[in] exposureTimeRange Exposure time range, in nanoseconds.
60 * @see ISensorMode::getExposureTimeRange()
61 * @todo Document implications of quantization.
62 *
63 * @returns success/status of the call.
64 */
65 virtual Status setExposureTimeRange(const Range<uint64_t>& exposureTimeRange) = 0;
66
67 /**
68 * Returns the exposure time range of the source, in nanoseconds.
69 */
70 virtual Range<uint64_t> getExposureTimeRange() const = 0;
71
72 /**
73 * Sets the focus position, in focuser units. If the position
74 * is set outside of the focuser limits, the position will be clamped.
75 * @param[in] position The new focus position, in focuser units.
76 * @see ICameraProperties::getFocusPositionRange()
77 *
78 * @returns success/status of the call.
79 */
80 virtual Status setFocusPosition(int32_t position) = 0;
81
82 /**
83 * Returns the focus position, in focuser units.
84 */
85 virtual int32_t getFocusPosition() const = 0;
86
87 /**
88 * Sets the frame duration range, in nanoseconds.
89 * If frame range is out of bounds of the current sensor mode,
90 * the capture's frame duration will be as close as possible to the range specified.
91 * @param[in] frameDurationRange Frame duration range, in nanoseconds
92 * @see ISensorMode::getFrameDurationRange()
93 *
94 * @returns success/status of the call.
95 */
96 virtual Status setFrameDurationRange(const Range<uint64_t>& frameDurationRange) = 0;
97
98 /**
99 * Returns the frame duration range, in nanoseconds.
100 */
101 virtual Range<uint64_t> getFrameDurationRange() const = 0;
102
103 /**
104 * Sets the gain range for the sensor.
105 * The range has to be within the max and min reported in the CameraProperties
106 * Otherwise the range will be clipped.
107 * @param[in] gainRange scalar gain range
108 * @see ISensorMode::getAnalogGainRange()
109 *
110 * @returns success/status of the call.
111 */
112 virtual Status setGainRange(const Range<float>& gainRange) = 0;
113
114 /**
115 * Returns the gain range.
116 */
117 virtual Range<float> getGainRange() const = 0;
118
119 /**
120 * Sets the sensor mode.
121 * Note that changing sensor mode from one capture to the next may result in
122 * multiple sensor frames being dropped between the two captures.
123 * @param[in] mode Desired sensor mode for the capture.
124 * @see ICameraProperties::getAllSensorModes()
125 *
126 * @returns success/status of the call.
127 */
128 virtual Status setSensorMode(SensorMode* mode) = 0;
129
130 /**
131 * Returns the sensor mode.
132 */
133 virtual SensorMode* getSensorMode() const = 0;
134
135 /**
136 * Sets the user-specified optical black levels.
137 * These values will be ignored unless <tt>getOpticalBlackEnable() == true</tt>
138 * Values are floating point in the range [0,1) normalized based on sensor bit depth.
139 * @param[in] opticalBlackLevels opticalBlack levels in range [0,1) per bayer phase
140 *
141 * @returns success/status of the call.
142 */
143 virtual Status setOpticalBlack(const BayerTuple<float>& opticalBlackLevels) = 0;
144
145 /**
146 * Returns user-specified opticalBlack level per bayer phase.
147 *
148 * @returns opticalBlackLevels
149 */
150 virtual BayerTuple<float> getOpticalBlack() const = 0;
151
152 /**
153 * Sets whether or not user-provided optical black levels are used.
154 * @param[in] enable If @c true, Argus will use the user-specified optical black levels.
155 * @see setOpticalBlack()
156 * If @c false, the Argus implementation will choose the optical black values.
157 *
158 * @returns success/status of the call.
159 */
160 virtual Status setOpticalBlackEnable(bool enable) = 0;
161
162 /**
163 * Returns whether user-specified optical black levels are enabled.
164 * If false, the Argus implementation will choose the optical black values.
165 * @see setOpticalBlackEnable()
166 *
167 * @returns enable
168 */
169 virtual bool getOpticalBlackEnable() const = 0;
170
171
172 protected:
173 ~ISourceSettings() {}
174 };
175
176 /**
177 * @class IAutoControlSettings
178 *
179 * Interface to the auto control settings (provided by IRequest::getAutoControlSettings()).
180 *
181 * @ingroup ArgusAutoControlSettings
182 */
183 DEFINE_UUID(InterfaceID, IID_AUTO_CONTROL_SETTINGS, 1f2ad1c6,cb13,440b,bc95,3f,fd,0d,19,91,db);
184 class IAutoControlSettings : public Interface
185 {
186 public:
187 static const InterfaceID& id() { return IID_AUTO_CONTROL_SETTINGS; }
188
189 /**
190 * Sets the AE antibanding mode.
191 * @param[in] mode The requested antibanding mode.
192 *
193 * @returns success/status of the call.
194 */
195 virtual Status setAeAntibandingMode(AeAntibandingMode mode) = 0;
196
197 /**
198 * Returns the AE antibanding mode.
199 */
200 virtual AeAntibandingMode getAeAntibandingMode() const = 0;
201
202 /**
203 * Sets the AE lock. When locked, AE will maintain constant exposure.
204 * @param[in] lock If @c true, locks AE at its current exposure.
205 *
206 * @returns success/status of the call.
207 */
208 virtual Status setAeLock(bool lock) = 0;
209
210 /**
211 * Returns the AE lock.
212 */
213 virtual bool getAeLock() const = 0;
214
215 /**
216 * Sets the AE regions of interest.
217 * If no regions are specified, the entire image is the region of interest.
218 * @param[in] regions The AE regions of interest.
219 * The maximum number of regions is returned by @c ICameraProperties::getMaxAeRegions().
220 *
221 * @returns success/status of the call.
222 */
223 virtual Status setAeRegions(const std::vector<AcRegion>& regions) = 0;
224
225 /**
226 * Returns the AE regions of interest.
227 * @param[out] regions A vector that will be populated with the AE regions of interest.
228 *
229 * @returns success/status of the call.
230 */
231 virtual Status getAeRegions(std::vector<AcRegion>* regions) const = 0;
232
233 /**
234 * Sets the AWB lock.
235 * @param[in] lock If @c true, locks AWB at its current state.
236 *
237 * @returns success/status of the call.
238 */
239 virtual Status setAwbLock(bool lock) = 0;
240
241 /**
242 * Returns the AWB lock.
243 */
244 virtual bool getAwbLock() const = 0;
245
246 /**
247 * Sets the AWB mode.
248 * @param[in] mode The new AWB mode.
249 *
250 * @returns success/status of the call.
251 */
252 virtual Status setAwbMode(const AwbMode& mode) = 0;
253
254 /**
255 * Returns the AWB mode.
256 */
257 virtual AwbMode getAwbMode() const = 0;
258
259 /**
260 * Sets the AWB regions of interest.
261 * If no regions are specified, the entire image is the region of interest.
262 * @param[in] regions The AWB regions of interest.
263 * The maximum number of regions is returned by @c ICameraProperties::getMaxAwbRegions().
264 *
265 * @returns success/status of the call.
266 */
267 virtual Status setAwbRegions(const std::vector<AcRegion>& regions) = 0;
268
269 /**
270 * Returns the AWB regions of interest.
271 * @param[out] regions A vector that will be populated with the AWB regions of interest.
272 *
273 * @returns success/status of the call.
274 */
275 virtual Status getAwbRegions(std::vector<AcRegion>* regions) const = 0;
276
277 /**
278 * Sets the Manual White Balance gains.
279 * @param[in] gains The Manual White Balance Gains
280 *
281 * @returns success/status of the call.
282 */
283 virtual Status setWbGains(const BayerTuple<float>& gains) = 0;
284
285 /**
286 * Returns the Manual White Balance gains.
287 *
288 * @returns Manual White Balance Gains structure
289 */
290 virtual BayerTuple<float> getWbGains() const = 0;
291
292 /**
293 * Returns the size of the color correction matrix.
294 */
295 virtual Size2D<uint32_t> getColorCorrectionMatrixSize() const = 0;
296
297 /**
298 * Sets the user-specified color correction matrix.
299 * This matrix will be ignored unless <tt>getColorCorrectionMatrixEnable() == true</tt>.
300 * The active color correction matrix used for image processing may be internally modified
301 * to account for the active color saturation value (either user-specified or automatically
302 * generated, after biasing, @see setColorSaturation and @see setColorSaturationBias).
303 * @param[in] matrix A color correction matrix that maps sensor RGB to linear sRGB. This matrix
304 * is given in row-major order and must have the size w*h, where w and h are
305 * the width and height of the Size returned by getColorCorrectionMatrixSize()
306 *
307 * @returns success/status of the call.
308 */
309 virtual Status setColorCorrectionMatrix(const std::vector<float>& matrix) = 0;
310
311 /**
312 * Returns the user-specified color correction matrix.
313 * @param[out] matrix A matrix that will be populated with the CCM.
314 *
315 * @returns success/status of the call.
316 */
317 virtual Status getColorCorrectionMatrix(std::vector<float>* matrix) const = 0;
318
319 /**
320 * Enables the user-specified color correction matrix.
321 * @param[in] enable If @c true, libargus uses the user-specified matrix.
322 * @see setColorCorrectionMatrix()
323 *
324 * @returns success/status of the call.
325 */
326 virtual Status setColorCorrectionMatrixEnable(bool enable) = 0;
327
328 /**
329 * Returns the enable for the user-specified color correction matrix.
330 */
331 virtual bool getColorCorrectionMatrixEnable() const = 0;
332
333 /**
334 * Sets the user-specified absolute color saturation. This must be enabled via
335 * @see setColorSaturationEnable, otherwise saturation will be determined automatically.
336 * This saturation value may be used to modify the color correction matrix used
337 * for processing (@see setColorCorrectionMatrix), and these changes will be reflected
338 * in the color correction matrix output to the capture metadata.
339 * @param[in] saturation The absolute color saturation. Acceptable values are in
340 * [0.0, 2.0], and the default value is 1.0.
341
342 * @returns success/status of the call.
343 */
344 virtual Status setColorSaturation(float saturation) = 0;
345
346 /**
347 * Returns the user-specified absolute color saturation (@see setColorSaturation).
348 */
349 virtual float getColorSaturation() const = 0;
350
351 /**
352 * Enables the user-specified absolute color saturation.
353 * @param[in] enable If @c true, libargus uses the user-specified color saturation.
354 * @see setColorSaturation()
355 *
356 * @returns success/status of the call.
357 */
358 virtual Status setColorSaturationEnable(bool enable) = 0;
359
360 /**
361 * Returns the enable for the user-specified color saturation.
362 */
363 virtual bool getColorSaturationEnable() const = 0;
364
365 /**
366 * Sets the color saturation bias. This bias is used to multiply the active saturation
367 * value, either the user-specified or the automatically generated value depending on the state
368 * of @see getColorSaturationEnable, and produces the final saturation value to use for
369 * capture processing. This is used primarily to tweak automatically generated saturation
370 * values when the application prefers more or less saturation than what the implementation
371 * or hardware generates by default. The final saturation value (after biasing) may affect the
372 * color correction matrix used for processing (@see setColorCorrectionMatrix).
373 * @param[in] bias The color saturation bias. Acceptable values are in [0.0, 2.0], where
374 * 1.0 does not modify the saturation (default), 0.0 is fully desaturated
375 * (greyscale), and 2.0 is highly saturated.
376 *
377 * @returns success/status of the call.
378 */
379 virtual Status setColorSaturationBias(float bias) = 0;
380
381 /**
382 * Returns the color saturation bias.
383 */
384 virtual float getColorSaturationBias() const = 0;
385
386 /**
387 * Sets the exposure compensation.
388 * Exposure compensation is applied after AE is solved.
389 * @param[in] ev The exposure adjustment step in stops.
390 *
391 * @returns success/status of the call.
392 */
393 virtual Status setExposureCompensation(float ev) = 0;
394
395 /**
396 * Returns the exposure compensation.
397 */
398 virtual float getExposureCompensation() const = 0;
399
400 /**
401 * Returns the number of elements required for the tone map curve.
402 * @param[in] channel The color channel the curve size corresponds to.
403 */
404 virtual uint32_t getToneMapCurveSize(RGBChannel channel) const = 0;
405
406 /**
407 * Sets the user-specified tone map curve for a channel on the stream.
408 * The user-specified tone map will be ignored unless <tt>getToneMapCurveEnable() == true</tt>.
409 * @param[in] channel The color the curve corresponds to.
410 * @param[in] curve A float vector that describes the LUT.
411 * The number of elements must match the number of elements
412 * returned from getToneMapCurve() of the same channel.
413 *
414 * @returns success/status of the call.
415 */
416 virtual Status setToneMapCurve(RGBChannel channel, const std::vector<float>& curve) = 0;
417
418 /**
419 * Returns the user-specified tone map curve for a channel on the stream.
420 * @param[in] channel The color the curve corresponds to.
421 * @param[out] curve A vector that will be populated by the tone map curve for the specified
422 * color channel.
423 *
424 * @returns success/status of the call.
425 */
426 virtual Status getToneMapCurve(RGBChannel channel, std::vector<float>* curve) const = 0;
427
428 /**
429 * Enables the user-specified tone map.
430 * @param[in] enable If @c true, libargus uses the user-specified tone map.
431 *
432 * @returns success/status of the call.
433 */
434 virtual Status setToneMapCurveEnable(bool enable) = 0;
435
436 /**
437 * Returns the enable for the user-specified tone map.
438 */
439 virtual bool getToneMapCurveEnable() const = 0;
440
441 /**
442 * Sets the user-specified Isp Digital gain range.
443 * @param[in] gain The user-specified Isp Digital gain.
444 *
445 * @returns success/status of the call.
446 */
447 virtual Status setIspDigitalGainRange(const Range<float>& gain) = 0;
448
449 /**
450 * Returns the user-specified Isp Digital gain range.
451 *
452 * @returns Isp Digital gain
453 */
454 virtual Range<float> getIspDigitalGainRange() const = 0;
455
456 protected:
457 ~IAutoControlSettings() {}
458 };
459
460 /**
461 * @class IStreamSettings
462 *
463 * Interface to per-stream settings (provided by IRequest::getStreamSettings()).
464 *
465 * @ingroup ArgusStreamSettings
466 */
467 DEFINE_UUID(InterfaceID, IID_STREAM_SETTINGS, c477aeaf,9cc8,4467,a834,c7,07,d7,b6,9f,a4);
468 class IStreamSettings : public Interface
469 {
470 public:
471 static const InterfaceID& id() { return IID_STREAM_SETTINGS; }
472
473 /**
474 * Sets the clip rectangle for the stream.
475 * A clip rectangle is a normalized rectangle
476 * with valid coordinates contained in the [0.0,1.0] range.
477 * @param[in] clipRect The clip rectangle.
478 *
479 * @returns success/status of the call.
480 */
481 virtual Status setSourceClipRect(const Rectangle<float>& clipRect) = 0;
482
483 /**
484 * Returns the clip rectangle for the stream.
485 */
486 virtual Rectangle<float> getSourceClipRect() const = 0;
487
488 /**
489 * Sets whether or not post-processing is enabled for this stream.
490 * Post-processing features are controlled on a per-Request basis and all streams share the
491 * same post-processing control values, but this enable allows certain streams to be excluded
492 * from all post-processing. The current controls defined to be a part of "post-processing"
493 * includes:
494 * - Denoise
495 * - Video Stabilization
496 * Default value is true.
497 */
498 virtual void setPostProcessingEnable(bool enable) = 0;
499
500 /**
501 * Returns the post-processing enable for the stream.
502 */
503 virtual bool getPostProcessingEnable() const = 0;
504
505 protected:
506 ~IStreamSettings() {}
507 };
508
509 /**
510 * @class IDenoiseSettings
511 *
512 * Interface to denoise settings.
513 *
514 * @ingroup ArgusRequest
515 */
516 DEFINE_UUID(InterfaceID, IID_DENOISE_SETTINGS, 7A461D20,6AE1,11E6,BDF4,08,00,20,0C,9A,66);
517 class IDenoiseSettings : public Interface
518 {
519 public:
520 static const InterfaceID& id() { return IID_DENOISE_SETTINGS; }
521
522 /**
523 * Sets the denoise (noise reduction) mode for the request.
524 * @param[in] mode The denoise mode:
525 * OFF: Denoise algorithms are disabled.
526 * FAST: Noise reduction will be enabled, but it will not slow down
527 * the capture rate.
528 * HIGH_QUALITY: Maximum noise reduction will be enabled to achieve
529 * the highest quality, but may slow down the capture rate.
530 * @returns success/status of the call.
531 */
532 virtual Status setDenoiseMode(const DenoiseMode& mode) = 0;
533
534 /**
535 * Returns the denoise mode for the request.
536 */
537 virtual DenoiseMode getDenoiseMode() const = 0;
538
539 /**
540 * Sets the strength for the denoise operation.
541 * @param[in] strength The denoise strength. This must be within the range [0.0, 1.0], where
542 * 0.0 is the least and 1.0 is the most amount of noise reduction that can be
543 * applied. This denoise strength is relative to the current noise reduction mode;
544 * using a FAST denoise mode with a full strength of 1.0 may not perform as well
545 * as using a HIGH_QUALITY mode with a lower relative strength.
546 * @returns success/status of the call.
547 */
548 virtual Status setDenoiseStrength(float strength) = 0;
549
550 /**
551 * Returns the denoise strength.
552 */
553 virtual float getDenoiseStrength() const = 0;
554
555 protected:
556 ~IDenoiseSettings() {}
557 };
558
559 /**
560 * @class IEdgeEnhanceSettings
561 *
562 * Interface to edge enhancement settings.
563 *
564 * @ingroup ArgusRequest
565 */
566 DEFINE_UUID(InterfaceID, IID_EDGE_ENHANCE_SETTINGS, 7A461D21,6AE1,11E6,BDF4,08,00,20,0C,9A,66);
567 class IEdgeEnhanceSettings : public Interface
568 {
569 public:
570 static const InterfaceID& id() { return IID_EDGE_ENHANCE_SETTINGS; }
571
572 /**
573 * Sets the edge enhancement mode for the request.
574 * @param[in] mode The edge enhancement mode:
575 * OFF: Edge enhancement algorithms are disabled.
576 * FAST: Edge enhancement will be enabled, but it will not slow down
577 * the capture rate.
578 * HIGH_QUALITY: Maximum edge enhancement will be enabled to achieve
579 * the highest quality, but may slow down the capture rate.
580 * @returns success/status of the call.
581 */
582 virtual Status setEdgeEnhanceMode(const EdgeEnhanceMode& mode) = 0;
583
584 /**
585 * Returns the edge enhancement mode for the request.
586 */
587 virtual EdgeEnhanceMode getEdgeEnhanceMode() const = 0;
588
589 /**
590 * Sets the strength for the edge enhancement operation.
591 * @param[in] strength The edge enhancement strength. This must be within the range [0.0, 1.0],
592 * where 0.0 is the least and 1.0 is the most amount of edge enhancement that can be
593 * applied. This strength is relative to the current edge enhancement mode; using
594 * a FAST edge enhancement mode with a full strength of 1.0 may not perform as well
595 * as using a HIGH_QUALITY mode with a lower relative strength.
596 * @returns success/status of the call.
597 */
598 virtual Status setEdgeEnhanceStrength(float strength) = 0;
599
600 /**
601 * Returns the edge enhancement strength.
602 */
603 virtual float getEdgeEnhanceStrength() const = 0;
604
605 protected:
606 ~IEdgeEnhanceSettings() {}
607 };
608
609 /**
610 * @class IVideoStabilizationSettings
611 *
612 * Interface to video stabilization settings.
613 *
614 * @ingroup ArgusRequest
615 */
616 DEFINE_UUID(InterfaceID, IID_VIDEO_STABILIZATION_SETTINGS, 7A461D22,6AE1,11E6,BDF4,08,00,20,0C,9A,66);
617 class IVideoStabilizationSettings : public Interface
618 {
619 public:
620 static const InterfaceID& id() { return IID_VIDEO_STABILIZATION_SETTINGS; }
621
622 /**
623 * Sets the video stabilization mode to use for the request.
624 * @param[in] mode The video stabilization mode.
625 *
626 * @returns success/status of the call.
627 */
628 virtual Status setVideoStabilizationMode(const VideoStabilizationMode& mode) = 0;
629
630 /**
631 * Returns the video stabilization mode for the request.
632 */
633 virtual VideoStabilizationMode getVideoStabilizationMode() const = 0;
634
635 protected:
636 ~IVideoStabilizationSettings() {}
637 };
638
639 } // namespace Argus
640
641 #endif // _ARGUS_SETTINGS_H