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, which is used to configure the settings
144 * for OutputStream creation via createOutputStream.
145 *
146 * @param[out] status An optional pointer to return success/status.
147 *
148 * @returns The newly created OutputStream, or NULL on failure.
149 */
150 virtual OutputStreamSettings* createOutputStreamSettings(Status* status = NULL) = 0;
151
152 /**
153 * Creates an OutputStream object. All OutputStream objects are associated with
154 * and EGLStream, which is created and owned by this object and left in the CREATED
155 * state upon return. This does not connect as a producer for this EGLStream until
156 * the first request outputting to the stream; thus, the application is expected to
157 * connect the consumer to this stream before the first request is made otherwise the
158 * request will fail.
159 *
160 * @param[in] settings The settings to use for the new output stream.
161 * @param[out] status An optional pointer to return success/status.
162 *
163 * @returns The newly created OutputStream, or NULL on failure.
164 */
165 virtual OutputStream* createOutputStream(const OutputStreamSettings* settings,
166 Status* status = NULL) = 0;
167
168 /**
169 * Returns true if there is a streaming request in place.
170 */
171 virtual bool isRepeating() const = 0;
172
173 /**
174 * Sets up a repeating request. This is a convenience method that will queue
175 * a request whenever the request queue is empty and the camera is ready to
176 * accept new requests.
177 *
178 * To stop repeating the request, call stopRepeat().
179 *
180 * @param[in] request The request to repeat.
181 *
182 * @returns success/status of the call.
183 */
184 virtual Status repeat(const Request* request) = 0;
185
186 /**
187 * Sets up a repeating burst request. This is a convenience method that will queue
188 * a request whenever the request queue is empty and the camera is ready to
189 * accept new requests.
190 *
191 * To stop repeating the requests, call stopRepeat().
192 *
193 * @param[in] requestList The list of requests that make up the repeating burst.
194 *
195 * @returns success/status of the call.
196 */
197 virtual Status repeatBurst(const std::vector<const Request*>& requestList) = 0;
198
199 /**
200 * Shuts down any repeating capture.
201 *
202 * @returns The range of capture ids generated by the most recent repeat() / repeatBurst() call.
203 * Note that some captures within that range may have been generated by explicit capture() calls
204 * made while the repeating capture was in force.
205 * If no captures were generated by the most recent repeat() / repeatBurst() call,
206 * <tt>Range<uint32_t>(0,0)</tt> will be returned.
207 */
208 virtual Range<uint32_t> stopRepeat() = 0;
209
210 /**
211 * Waits until all pending captures are complete.
212 *
213 * @param[in] timeout The timeout value (in nanoseconds) for this call.
214 * If the pipe has not become idle when the timeout expires,
215 * the call will return STATUS_TIMEOUT.
216 */
217 virtual Status waitForIdle(uint64_t timeout = TIMEOUT_INFINITE) const = 0;
218
219 protected:
220 ~ICaptureSession() {}
221 };
222
223 } // namespace Argus
224
225 #endif // _ARGUS_CAPTURE_SESSION_H