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
CaptureSession.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: Capture Session API</b>
32 *
33 * @b Description: Defines the CaptureSession object and interface.
34 */
35
36 #ifndef _ARGUS_CAPTURE_SESSION_H
37 #define _ARGUS_CAPTURE_SESSION_H
38
39 namespace Argus
40 {
41
42 /**
43 * Object that controls all operations on a single sensor.
44 *
45 * A capture session is bound to a single sensor (or, in future, a group of synchronized sensors)
46 * and provides methods to perform captures on that sensor (via the ICaptureSession interface).
47 *
48 * @defgroup ArgusCaptureSession CaptureSession
49 * @ingroup ArgusObjects
50 */
51 class CaptureSession : public InterfaceProvider, public Destructable
52 {
53 protected:
54 ~CaptureSession() {}
55 };
56
57 /**
58 * @class ICaptureSession
59 *
60 * Interface to the core CaptureSession methods.
61 *
62 * @ingroup ArgusCaptureSession
63 */
64 DEFINE_UUID(InterfaceID, IID_CAPTURE_SESSION, 813644f5,bc21,4013,af44,dd,da,b5,7a,9d,13);
65 class ICaptureSession : public Interface
66 {
67 public:
68 static const InterfaceID& id() { return IID_CAPTURE_SESSION; }
69
70 /**
71 * Removes all previously submitted requests from the queue. When all requests
72 * are cancelled, both the FIFO and the streaming requests will be removed.
73 * If repeat captures are enabled, an implicit call to ICaptureSession::stopRepeat()
74 * will be made before cancelling the requests.
75 *
76 * @returns success/status of this call.
77 */
78 virtual Status cancelRequests() = 0;
79
80 /**
81 * Submits a single capture request to the request queue.
82 * The runtime will queue a copy of the request. The client can
83 * submit the same request instance in a future call.
84 * The request will be copied by the runtime.
85 *
86 * @param[in] request Parameters for the capture.
87 * @param[in] timeout The timeout in nanoseconds. The camera device will
88 * try to issue the request within the timeout period. If it can't it
89 * will return and set @c status to STATUS_UNAVAILABLE.
90 * @param[out] status An optional pointer to return success/status.
91 *
92 * @returns the capture id, a number that uniquely identifies (within this session) the request.
93 * If the submission request failed, zero will be returned.
94 * The request could fail because the timeout is reached,
95 * or because some parameter(s) of the @c request are invalid.
96 */
97 virtual uint32_t capture(const Request* request,
98 uint64_t timeout = TIMEOUT_INFINITE,
99 Status* status = NULL) = 0;
100
101 /**
102 * Submits a burst to the request queue.
103 * The runtime will queue a copy of the burst.
104 * The runtime will either accept the entire burst or refuse it completely
105 * (that is, no partial bursts will be accepted).
106 *
107 * @param[in] requestList The list of requests that make up the burst.
108 * @param[in] timeout The timeout in nanoseconds. The camera device will try to issue
109 * the request within the timeout period. If it can't it will return and set
110 * @c status to STATUS_UNAVAILABLE.
111 * @param[out] status An optional pointer to return success/status.
112 *
113 * @returns the capture id of the capture associated with the first request in the burst.
114 * The capture id will increment by one for the captures associated with each successive
115 * request.
116 * If the submission request failed, zero will be returned.
117 * The request could fail because the timeout is reached,
118 * or because some parameter(s) of the @c request are invalid.
119 */
120 virtual uint32_t captureBurst(const std::vector<const Request*>& requestList,
121 uint64_t timeout = TIMEOUT_INFINITE,
122 Status* status = NULL) = 0;
123
124 /**
125 * Returns the maximum number of capture requests that can be included in a burst capture.
126 */
127 virtual uint32_t maxBurstRequests() const = 0;
128
129 /**
130 * Creates a request object that can be later used with this CaptureSession.
131 *
132 * @param[in] intent Optional parameter that specifies the intent of the capture request and
133 * instructs the driver to populate the request with recommended settings
134 * for that intent.
135 * @param[out] status An optional pointer to return success/status.
136 *
137 * @see ICaptureMetadata::getClientData()
138 */
139 virtual Request* createRequest(const CaptureIntent& intent = CAPTURE_INTENT_PREVIEW,
140 Status* status = NULL) = 0;
141
142 /**
143 * Creates an OutputStreamSettings object that is used to configure the creation of
144 * an OutputStream (see createOutputStream). The type of OutputStream that will be
145 * configured and created by these settings are determined by the StreamType.
146 *
147 * @param[in] type The type of the OutputStream to configure/create with these settings.
148 * @param[out] status An optional pointer to return success/status.
149 *
150 * @returns The newly created OutputStreamSettings, or NULL on failure.
151 */
152 virtual OutputStreamSettings* createOutputStreamSettings(const StreamType& type,
153 Status* status = NULL) = 0;
154
155 /**
156 * Creates an OutputStream object using the settings configured by an OutputStreamSettings
157 * object (see createOutputStreamSettings).
158 *
159 * @param[in] settings The settings to use for the new output stream.
160 * @param[out] status An optional pointer to return success/status.
161 *
162 * @returns The newly created OutputStream, or NULL on failure.
163 */
164 virtual OutputStream* createOutputStream(const OutputStreamSettings* settings,
165 Status* status = NULL) = 0;
166
167 /**
168 * Returns true if there is a streaming request in place.
169 */
170 virtual bool isRepeating() const = 0;
171
172 /**
173 * Sets up a repeating request. This is a convenience method that will queue
174 * a request whenever the request queue is empty and the camera is ready to
175 * accept new requests.
176 *
177 * To stop repeating the request, call stopRepeat().
178 *
179 * @param[in] request The request to repeat.
180 *
181 * @returns success/status of the call.
182 */
183 virtual Status repeat(const Request* request) = 0;
184
185 /**
186 * Sets up a repeating burst request. This is a convenience method that will queue
187 * a request whenever the request queue is empty and the camera is ready to
188 * accept new requests.
189 *
190 * To stop repeating the requests, call stopRepeat().
191 *
192 * @param[in] requestList The list of requests that make up the repeating burst.
193 *
194 * @returns success/status of the call.
195 */
196 virtual Status repeatBurst(const std::vector<const Request*>& requestList) = 0;
197
198 /**
199 * Shuts down any repeating capture.
200 *
201 * @returns The range of capture ids generated by the most recent repeat() / repeatBurst() call.
202 * Note that some captures within that range may have been generated by explicit capture() calls
203 * made while the repeating capture was in force.
204 * If no captures were generated by the most recent repeat() / repeatBurst() call,
205 * <tt>Range<uint32_t>(0,0)</tt> will be returned.
206 */
207 virtual Range<uint32_t> stopRepeat() = 0;
208
209 /**
210 * Waits until all pending captures are complete.
211 *
212 * @param[in] timeout The timeout value (in nanoseconds) for this call.
213 * If the pipe has not become idle when the timeout expires,
214 * the call will return STATUS_TIMEOUT.
215 */
216 virtual Status waitForIdle(uint64_t timeout = TIMEOUT_INFINITE) const = 0;
217
218 protected:
219 ~ICaptureSession() {}
220 };
221
222 } // namespace Argus
223
224 #endif // _ARGUS_CAPTURE_SESSION_H