Libargus API
Libargus Camera API
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
InternalFrameCount.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: Internal Frame Count</b>
32  *
33  * @b Description: This file defines the InternalFrameCount extension.
34  * @ingroup ArgusExtInternalFrameCount
35  */
36 
37 #ifndef _ARGUS_INTERNAL_FRAME_COUNT_H
38 #define _ARGUS_INTERNAL_FRAME_COUNT_H
39 
40 namespace Argus
41 {
42 
43 /**
44  * Adds accessors for an internal frame count performance metric.
45  * The "internal frame count" is an implementation-dependent metric that may be
46  * used to detect performance issues and producer frame drops for libargus
47  * implementations that make use of internal captures.
48  *
49  * When a device is opened by a CaptureSession, the libargus implementation may
50  * begin to immediately capture and process frames from the device in order to
51  * initialize the camera subsystem even before a client request has been
52  * submitted. Similarly, frames may be captured and processed by the
53  * implementation when the client is idle or not ready for output in order to
54  * maintain the driver subsystem and/or auto-control state (exposure, white
55  * balance, etc). These captures are started and processed entirely within the
56  * libargus implementation, with no inputs from or outputs to the client
57  * application, and so are referred to as "internal" captures. These internal
58  * captures are typically submitted when there are no client requests in the
59  * capture queue or no stream buffers available for output within a sensor
60  * frame period, and so knowing when an internal capture has been submitted can
61  * be used to detect application or performance issues in cases where these
62  * conditions are not expected to occur. This extension provides this
63  * information in the form of an "internal frame count", which is the total
64  * number of captures submitted by the session including both the internal
65  * captures as well as client-submitted requests. If an internal frame count
66  * gap appears between two client-submitted captures, this means that one or
67  * more internal captures have been performed.
68  *
69  * When an application is saturating the capture queue to maintain driver
70  * efficiency, either manually or by using repeat capture requests, the
71  * internal frame count can be used to detect when internal captures are
72  * submitted due to a lack of available output stream buffers. This situation
73  * leads to sensor frames that are not output to the client's output stream,
74  * which is usually an undesirable behavior that is referred to as "producer
75  * frame drop". This is generally caused by a high consumer processing time,
76  * which starves the stream’s available buffer pool, and can often be resolved
77  * by decreasing the consumer processing time (reducing the time a buffer is
78  * acquired, decreasing system load, increasing hardware clocks, etc.)
79  *
80  * @defgroup ArgusExtInternalFrameCount Ext::InternalFrameCount
81  * @ingroup ArgusExtensions
82  */
83 DEFINE_UUID(ExtensionName, EXT_INTERNAL_FRAME_COUNT, 37afdbda,0020,4f91,957b,46,ea,eb,79,80,c7);
84 
85 namespace Ext
86 {
87 
88 /**
89  * @class IInternalFrameCount
90  *
91  * Interface used to query the internal frame count for a request.
92  *
93  * Since internal captures do not generate events, detecting internal captures
94  * must be done by comparing the internal capture count of successive client-
95  * submitted capture requests.
96  *
97  * This interface is available from:
98  * - CaptureMetadata objects.
99  * - Event objects of type EVENT_TYPE_CAPTURE_STARTED.
100  *
101  * @ingroup ArgusCaptureMetadata ArgusEventCaptureStarted ArgusExtInternalFrameCount
102  */
103 DEFINE_UUID(InterfaceID, IID_INTERNAL_FRAME_COUNT, c21a7ba2,2b3f,4275,8469,a2,56,34,93,53,93);
105 {
106 public:
107  static const InterfaceID& id() { return IID_INTERNAL_FRAME_COUNT; }
108 
109  /**
110  * Returns the internal frame count for the request.
111  */
112  virtual uint64_t getInternalFrameCount() const = 0;
113 
114 protected:
116 };
117 
118 } // namespace Ext
119 
120 } // namespace Argus
121 
122 #endif