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-2022, 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 * Connect the input stream side consumers to input streams.
82 *
83 * @param[in] request Parameters for the capture.
84 * @param[in] numRequests Number of capture requests
85 *
86 * @returns success/status of this call.
87 */
88
89 virtual Status connectAllRequestInputStreams(const Request *requests,
90 uint32_t numRequests) = 0;
91
92 /**
93 * Submits a single capture request.
94 * For blocking capture session (created by ICameraProvider::createBlockingCaptureSession),
95 * it will wait until the request is accepted by lower level driver.
96 * For non-blocking capture session (created by ICameraProvider::createCaptureSession),
97 * it will queue a copy of the request to a queue and return.
98 *
99 * The client can submit the same request instance in a future call.
100 * The request will be copied by the runtime.
101 *
102 * @param[in] request Parameters for the capture.
103 * @param[in] timeout The timeout in nanoseconds. The camera device will
104 * try to issue the request within the timeout period. If it can't it
105 * will return and set @c status to STATUS_UNAVAILABLE.
106 * @param[out] status An optional pointer to return success/status.
107 *
108 * @returns the capture id, a number that uniquely identifies (within this session) the request.
109 * If the submission request failed, zero will be returned.
110 * The request could fail because the timeout is reached,
111 * or because some parameter(s) of the @c request are invalid.
112 */
113 virtual uint32_t capture(const Request* request,
114 uint64_t timeout = TIMEOUT_INFINITE,
115 Status* status = NULL) = 0;
116
117 /**
118 * Submits a burst of requests.
119 *
120 * For blocking capture session (created by ICameraProvider::createBlockingCaptureSession),
121 * it will wait until the first request is accepted by lower level driver.
122 * For non-blocking capture session (created by ICameraProvider::createCaptureSession),
123 * it will queue a copy of the requests to a queue and return.
124
125 * The runtime will either accept the entire burst or refuse it completely
126 * (that is, no partial bursts will be accepted).
127 *
128 * @param[in] requestList The list of requests that make up the burst.
129 * @param[in] timeout The timeout in nanoseconds. The camera device will try to issue
130 * the request within the timeout period. If it can't it will return and set
131 * @c status to STATUS_UNAVAILABLE.
132 * @param[out] status An optional pointer to return success/status.
133 *
134 * @returns the capture id of the capture associated with the first request in the burst.
135 * The capture id will increment by one for the captures associated with each successive
136 * request.
137 * If the submission request failed, zero will be returned.
138 * The request could fail because the timeout is reached,
139 * or because some parameter(s) of the @c request are invalid.
140 */
141 virtual uint32_t captureBurst(const std::vector<const Request*>& requestList,
142 uint64_t timeout = TIMEOUT_INFINITE,
143 Status* status = NULL) = 0;
144
145 /**
146 * Returns the maximum number of capture requests that can be included in a burst capture.
147 */
148 virtual uint32_t maxBurstRequests() const = 0;
149
150 /**
151 * Creates a request object that can be later used with this CaptureSession.
152 *
153 * @param[in] intent Optional parameter that specifies the intent of the capture request and
154 * instructs the driver to populate the request with recommended settings
155 * for that intent.
156 * @param[out] status An optional pointer to return success/status.
157 *
158 * @see ICaptureMetadata::getClientData()
159 */
160 virtual Request* createRequest(const CaptureIntent& intent = CAPTURE_INTENT_PREVIEW,
161 Status* status = NULL) = 0;
162
163 /**
164 * Creates an OutputStreamSettings object that is used to configure the creation of
165 * an OutputStream (see createOutputStream). The type of OutputStream that will be
166 * configured and created by these settings are determined by the StreamType.
167 *
168 * @param[in] type The type of the OutputStream to configure/create with these settings.
169 * @param[out] status An optional pointer to return success/status.
170 *
171 * @returns The newly created OutputStreamSettings, or NULL on failure.
172 */
173 virtual OutputStreamSettings* createOutputStreamSettings(const StreamType& type,
174 Status* status = NULL) = 0;
175
176 /**
177 * Creates an OutputStream object using the settings configured by an OutputStreamSettings
178 * object (see createOutputStreamSettings).
179 *
180 * @param[in] settings The settings to use for the new output stream.
181 * @param[out] status An optional pointer to return success/status.
182 *
183 * @returns The newly created OutputStream, or NULL on failure.
184 */
185 virtual OutputStream* createOutputStream(const OutputStreamSettings* settings,
186 Status* status = NULL) = 0;
187
188 /**
189 * Creates an InputStreamSettings object that is used to configure the creation of
190 * an InputStream (see createInputStream). The type of InputStream that will be
191 * configured and created by these settings are determined by the StreamType.
192 *
193 * @param[in] type The type of the InputStream to configure/create with these settings.
194 * @param[out] status An optional pointer to return success/status.
195 *
196 * @returns The newly created InputStreamSettings, or NULL on failure.
197 */
198 virtual InputStreamSettings* createInputStreamSettings(const StreamType& type,
199 Status* status = NULL) = 0;
200
201 /**
202 * Creates an InputStream object using the settings configured by an InputStreamSettings
203 * object (see createInputStreamSettings).
204 *
205 * @param[in] settings The settings to use for the new input stream.
206 * @param[out] status An optional pointer to return success/status.
207 *
208 * @returns The newly created InputStream, or NULL on failure.
209 */
210 virtual InputStream* createInputStream(const InputStreamSettings* settings,
211 Status* status = NULL) = 0;
212
213 /**
214 * Returns true if there is a streaming request in place.
215 */
216 virtual bool isRepeating() const = 0;
217
218 /**
219 * Sets up a repeating request. This is a convenience method that will queue
220 * a request whenever the request queue is empty and the camera is ready to
221 * accept new requests.
222 *
223 * To stop repeating the request, call stopRepeat().
224 *
225 * @param[in] request The request to repeat.
226 *
227 * @returns success/status of the call.
228 */
229 virtual Status repeat(const Request* request) = 0;
230
231 /**
232 * Sets up a repeating burst request. This is a convenience method that will queue
233 * a request whenever the request queue is empty and the camera is ready to
234 * accept new requests.
235 *
236 * To stop repeating the requests, call stopRepeat().
237 *
238 * @param[in] requestList The list of requests that make up the repeating burst.
239 *
240 * @returns success/status of the call.
241 */
242 virtual Status repeatBurst(const std::vector<const Request*>& requestList) = 0;
243
244 /**
245 * Shuts down any repeating capture.
246 *
247 * @returns The range of capture ids generated by the most recent repeat() / repeatBurst() call.
248 * Note that some captures within that range may have been generated by explicit capture() calls
249 * made while the repeating capture was in force.
250 * If no captures were generated by the most recent repeat() / repeatBurst() call,
251 * <tt>Range<uint32_t>(0,0)</tt> will be returned.
252 */
253 virtual Range<uint32_t> stopRepeat() = 0;
254
255 /**
256 * Waits until all pending captures are complete.
257 *
258 * @param[in] timeout The timeout value (in nanoseconds) for this call.
259 * If the pipe has not become idle when the timeout expires,
260 * the call will return STATUS_TIMEOUT.
261 */
262 virtual Status waitForIdle(uint64_t timeout = TIMEOUT_INFINITE) const = 0;
263
264 protected:
265 ~ICaptureSession() {}
266 };
267
268 } // namespace Argus
269
270 #endif // _ARGUS_CAPTURE_SESSION_H