1/*
2 * Copyright (C) 2018 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.frameworks.cameraservice.device@2.0;
18
19import android.frameworks.cameraservice.common@2.0::Status;
20
21interface ICameraDeviceUser {
22    /**
23     * disconnect from using the camera device.
24     * This method must block till in-flight requests are completed and stop
25     * all the requests submitted through submitRequestList().
26     */
27    disconnect();
28
29    /**
30     * Retrieve the fast message queue to be optionally used in CaptureRequests,
31     * to pass the settings metadata.
32     * If the client decides to use FMQ, it must:
33     *  - Call getCaptureRequestMetadataQueue to retrieve the fast message queue
34     *  - In submitRequestList calls, for each request set the fmqMetadataSize
35     *    in the settings field of physicalCameraSettings, to the size of the
36     *    metadata.
37     *
38     * @return queue the queue that the client writes the request settings
39     *         metadata to.
40     */
41    getCaptureRequestMetadataQueue() generates (fmq_sync<uint8_t> queue);
42
43    /**
44     * Retrieve the fast message queue used along with
45     * ICameraDeviceCallback.onResultReceived.
46     *
47     * Note: The client's use of this function does not affect the hidl
48     * service's decision to use / not use FMQ to pass result metadata to the
49     * cleint.
50     *
51     * Clients implementing the callback must:
52     *  - Retrieve the queue using getCaptureResultMetadataQueue.
53     *  - In the implementation of ICameraDeviceCallback.onResultReceived, if
54     *    PhysicalCaptureResultInfo.physicalCameraMetadata has a valid
55     *    fmqMetadataSize (which is > 0), the metadata must be read from the FMQ,
56     *    else, it must be read from the metadata field.
57     *    The same applies to resultMetadata.
58     *
59     * @return queue the queue that the client reads the result metadata from.
60     */
61    getCaptureResultMetadataQueue() generates (fmq_sync<uint8_t> queue);
62
63    /**
64     * Submit a list of capture requests.
65     *
66     * Note: Clients must call submitRequestList() serially if they opt
67     *       to utilize an fmq (obtained by calling getCaptureRequestMetadataQueue)
68     *       for any CaptureRequest's physicalCameraSettings metadata.
69
70     * @param requestList The list of CaptureRequests
71     * @param isRepeating Whether the set of requests repeats indefinitely.
72     *
73     * @return status status code of the operation.
74     * @return submitInfo data structure containing the request id of the
75     *         capture request and the frame number of the last frame that will
76     *         be produced(In case the request is not repeating. Otherwise it
77     *         contains the frame number of the last request, of the previus
78     *         batch of repeating requests, if any. If there is no previous
79     *         batch, the frame number returned will be -1.)
80     */
81    submitRequestList(vec<CaptureRequest> requestList, bool isRepeating)
82        generates (Status status, SubmitInfo submitInfo);
83
84    /**
85     * Cancel the current repeating request.
86     *
87     * The current repeating request may be stopped by camera device due to an
88     * error.
89     *
90     * Calling this method when there is no active repeating request, will
91     * trigger Status::INVALID_OPERATION.
92     *
93     * @return status the status code of the opertion.
94     * @return frameNumber the frame number of the last frame that will be
95     *         produced from this repeating request. If there are no inflight
96     *         repeating requests, this will return -1 as the frameNumber.
97     *         If the status is not NO_ERROR, the frame number should not be
98     *         used.
99     */
100    cancelRepeatingRequest()
101        generates (Status status, int64_t frameNumber);
102
103    /*
104     * Begin device configuration.
105     *
106     * @return status the status code of the operation.
107     */
108    beginConfigure() generates (Status status);
109
110    /**
111     * End the device configuration.
112     *
113     * endConfigure must be called after stream configuration is complete
114     * (i.e. after a call to beginConfigure and subsequent
115     * createStream/deleteStream calls). It must be called before any
116     * requests can be submitted.
117     *
118     * @param operatingMode The kind of session to create; either NORMAL_MODE,
119     *        CONSTRAINED_HIGH_SPEED_MODE, or one of the vendor modes.
120     * @param sessionParams Session-wide camera parameters. Empty session
121     *        parameters are legal inputs.
122     *
123     * @return status the status code of the operation.
124     */
125    endConfigure(StreamConfigurationMode operatingMode,
126                 CameraMetadata sessionParams) generates (Status status);
127
128    /**
129     * delete the stream specified by streamId.
130     *
131     * Note: deleteStream() must only be called within a beginConfigure() and an
132     *       endConfigure() block.
133     *
134     * @param streamId the stream id of the stream to be deleted
135     * @return status the status code of the operation
136     */
137    deleteStream(int32_t streamId) generates (Status status);
138
139    /**
140     * Create an output stream based on the given output configuration.
141     *
142     * Note: createStream() must only be called within a beginConfigure() and an
143     *       endConfigure() block.
144     *
145     * @param outputConfiguration size, format, and other parameters for the
146     *        stream
147     * @return status the status code of the operation.
148     * @return streamID new stream ID generated.
149     */
150    createStream(OutputConfiguration outputConfiguration)
151        generates (Status status, int32_t streamID);
152
153    /**
154     * Create a default capture request for capturing an image.
155     *
156     * @param templateId the type of capture request to be created.
157     *
158     * @return status the status code of the operation.
159     * @return metadata the settings metadata of the request.
160     */
161    createDefaultRequest(TemplateId templateId)
162        generates (Status status, CameraMetadata metadata);
163
164    /**
165     * Block until the device is idle.
166     *
167     * Note: This method will not block and instead will fail with
168     *       Status::INVALID_OPERATION if there are active repeating requests.
169     *
170     * @return status the status code of the operation.
171     */
172    waitUntilIdle() generates (Status status);
173
174    /**
175     * flush all the requests pending on the device.
176     *
177     * @return status the status code of the operation.
178     * @return lastFrameNumber the frame number of the last frame flushed.
179     */
180    flush() generates (Status status, int64_t lastFrameNumber);
181
182    /**
183     * Update a previously set output configuration.
184     *
185     * Note: It is legal to call this method outside of
186     *       beginConfigure()/endConfigure() blocks and also when the device
187     *       is not idle.
188     *
189     * @param streamId the stream id whose output configuration needs to be
190     *        updated.
191     * @param outputConfiguration the new outputConfiguration.
192     *
193     * @return status the status code of the operation.
194     */
195    updateOutputConfiguration(
196            int32_t streamId, OutputConfiguration outputConfiguration)
197         generates (Status status);
198
199    /**
200      * Check whether a particular session configuration has camera device
201      * support.
202      *
203      * @param sessionConfiguration Specific session configuration to be verified.
204      *
205      * @return status the status code of the operation
206      * @return true  - in case the stream combination is supported.
207      *         false - in case there is no device support.
208      */
209    isSessionConfigurationSupported(SessionConfiguration sessionConfiguration)
210        generates (Status status, bool supported);
211};
212