Argus API Argus Camera API

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

- File List
- File Members

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