Libargus API
Libargus Camera API
 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  */
52 {
53 protected:
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:
266 };
267 
268 } // namespace Argus
269 
270 #endif // _ARGUS_CAPTURE_SESSION_H