Libargus API
Libargus Camera API
 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:
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);
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  */
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  */
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:
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);
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:
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);
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:
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);
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:
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);
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:
637 };
638 
639 } // namespace Argus
640 
641 #endif // _ARGUS_SETTINGS_H