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
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);
104 class IInternalFrameCount : public Interface
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:
115 ~IInternalFrameCount() {}
116 };
117
118 } // namespace Ext
119
120 } // namespace Argus
121
122 #endif