1/*
2 * Copyright (C) 2016 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.hardware.camera.device@1.0;
18
19import android.hardware.camera.common@1.0::types;
20import ICameraDeviceCallback;
21import ICameraDevicePreviewCallback;
22
23/**
24 * Camera device HAL, legacy version
25 *
26 * DEPRECATED. New devices are strongly recommended to use Camera HAL v3.2 or
27 * newer.
28 *
29 * Supports the android.hardware.Camera API, and the android.hardware.camera2
30 * API in LEGACY mode only.
31 *
32 * Will be removed in the Android P release.
33 */
34interface ICameraDevice {
35
36    /**
37     * Get camera device resource cost information.
38     *
39     * This method may be called at any time, including before open()
40     *
41     * @return status Status code for the operation, one of:
42     *     OK:
43     *         On success.
44     *     INTERNAL_ERROR:
45     *         An unexpected internal camera HAL error occurred, and the
46     *         resource cost is not available.
47     *     CAMERA_DISCONNECTED:
48     *         An external camera device has been disconnected, and is no longer
49     *         available. This camera device interface is now stale, and a new
50     *         instance must be acquired if the device is reconnected. All
51     *         subsequent calls on this interface must return
52     *         CAMERA_DISCONNECTED.
53     * @return resourceCost
54     *     The resources required to open this camera device, or unspecified
55     *     values if status is not OK.
56     */
57    getResourceCost() generates (Status status, CameraResourceCost resourceCost);
58
59    /**
60     * Get basic camera information.
61     *
62     * This method may be called at any time, including before open()
63     *
64     * @return status Status code for the operation, one of:
65     *     OK:
66     *         On success.
67     *     INTERNAL_ERROR:
68     *         An unexpected internal camera HAL error occurred, and the
69     *         camera information is not available.
70     *     CAMERA_DISCONNECTED:
71     *         An external camera device has been disconnected, and is no longer
72     *         available. This camera device interface is now stale, and a new
73     *         instance must be acquired if the device is reconnected. All
74     *         subsequent calls on this interface must return
75     *         CAMERA_DISCONNECTED.
76     * @return info Basic information about this camera device, or unspecified
77     *     values if status is not OK.
78     */
79    getCameraInfo() generates (Status status, CameraInfo info);
80
81    /**
82     * setTorchMode:
83     *
84     * Turn on or off the torch mode of the flash unit associated with a given
85     * camera ID. If the operation is successful, HAL must notify the framework
86     * torch state by invoking
87     * ICameraProviderCallback::torchModeStatusChange() with the new state.
88     *
89     * The camera device has a higher priority accessing the flash unit. When
90     * there are any resource conflicts, such as when open() is called to fully
91     * activate a camera device, the provider must notify the framework through
92     * ICameraProviderCallback::torchModeStatusChange() that the torch mode has
93     * been turned off and the torch mode state has become
94     * TORCH_MODE_STATUS_NOT_AVAILABLE. When resources to turn on torch mode
95     * become available again, the provider must notify the framework through
96     * ICameraProviderCallback::torchModeStatusChange() that the torch mode
97     * state has become TORCH_MODE_STATUS_AVAILABLE_OFF for set_torch_mode() to
98     * be called.
99     *
100     * When the framework calls setTorchMode() to turn on the torch mode of a
101     * flash unit, if HAL cannot keep multiple torch modes on simultaneously,
102     * HAL must turn off the torch mode that was turned on by
103     * a previous setTorchMode() call and notify the framework that the torch
104     * mode state of that flash unit has become TORCH_MODE_STATUS_AVAILABLE_OFF.
105     *
106     * @param torchMode The new mode to set the device flash unit to.
107     *
108     * @return status Status code for the operation, one of:
109     *     OK:
110     *         On a successful change to the torch state.
111     *     INTERNAL_ERROR:
112     *         The flash unit cannot be operated due to an unexpected internal
113     *         error.
114     *     ILLEGAL_ARGUMENT:
115     *         The camera ID is unknown.
116     *     CAMERA_IN_USE:
117     *         This camera device has been opened, so the torch cannot be
118     *         controlled until it is closed.
119     *     MAX_CAMERAS_IN_USE:
120     *         Due to other camera devices being open, or due to other
121     *         resource constraints, the torch cannot be controlled currently.
122     *     METHOD_NOT_SUPPORTED:
123     *         This provider does not support direct operation of flashlight
124     *         torch mode. The framework must open the camera device and turn
125     *         the torch on through the device interface.
126     *     OPERATION_NOT_SUPPORTED:
127     *         This camera device does not have a flash unit. This must
128     *         be returned if and only if parameter key flash-mode-values is not present.
129     *     CAMERA_DISCONNECTED:
130     *         An external camera device has been disconnected, and is no longer
131     *         available. This camera device interface is now stale, and a new
132     *         instance must be acquired if the device is reconnected. All
133     *         subsequent calls on this interface must return
134     *         CAMERA_DISCONNECTED.
135     *
136     */
137    setTorchMode(TorchMode mode) generates (Status status);
138
139    /**
140     * Dump state of the camera hardware.
141     *
142     * This must be callable at any time, whether the device is open or not.
143     *
144     * @param fd A native handle with one valid file descriptor. The descriptor
145     *     must be able to be used with dprintf() or equivalent to dump the
146     *     state of this camera device into the camera service dumpsys output.
147     *
148     * @return status The status code for this operation.
149     */
150    dumpState(handle fd) generates (Status status);
151
152    /**
153     * Open the camera device for active use.
154     *
155     * All methods besides getResourceCost(), getCameraInfo(), setTorchMode(),
156     * and dump() must not be called unless open() has been called successfully,
157     * and close() has not yet been called.
158     *
159     * @param callback Interface to invoke by the HAL for device callbacks.
160     * @return status Status code for the operation, one of:
161     *     OK:
162     *         On a successful open of the camera device.
163     *     INTERNAL_ERROR:
164     *         The camera device cannot be opened due to an internal
165     *         error.
166     *     ILLEGAL_ARGUMENT:
167     *         The callback handle is invalid (for example, it is null).
168     *     CAMERA_IN_USE:
169     *         This camera device is already open.
170     *     MAX_CAMERAS_IN_USE:
171     *         The maximal number of camera devices that can be
172     *         opened concurrently were opened already.
173     *     CAMERA_DISCONNECTED:
174     *         This external camera device has been disconnected, and is no
175     *         longer available. This interface is now stale, and a new instance
176     *         must be acquired if the device is reconnected. All subsequent
177     *         calls on this interface must return CAMERA_DISCONNECTED.
178     */
179    open(ICameraDeviceCallback callback) generates (Status status);
180
181
182    /*****
183     * All methods below this point must only be called between a successful
184     * open() call and a close() call.
185     */
186
187    /** Set the callback interface through which preview frames are sent */
188    setPreviewWindow(ICameraDevicePreviewCallback window)
189            generates (Status status);
190
191    /**
192     * Enable a message, or set of messages.
193     *
194     * @param msgType The bitfield of messages to enable.
195     */
196    enableMsgType(FrameCallbackFlags msgType);
197
198    /**
199     * Disable a message, or a set of messages.
200     *
201     * Once received a call to disableMsgType(CAMERA_MSG_VIDEO_FRAME), camera
202     * HAL must not rely on its client to call releaseRecordingFrame() to
203     * release video recording frames sent out by the cameral HAL before and
204     * after the disableMsgType(CAMERA_MSG_VIDEO_FRAME) call. Camera HAL
205     * clients must not modify/access any video recording frame after calling
206     * disableMsgType(CAMERA_MSG_VIDEO_FRAME).
207     *
208     * @param msgType The bitfield of messages to disable.
209     */
210    disableMsgType(FrameCallbackFlags msgType);
211
212    /**
213     * Query whether a message, or a set of messages, is enabled. Note that
214     * this is operates as an AND, if any of the messages queried are off, this
215     * must return false.
216     *
217     * @param msgType The bitfield of messages to query.
218     * @return enabled Whether all the specified flags are enabled.
219     */
220    msgTypeEnabled(FrameCallbackFlags msgType) generates (bool enabled);
221
222    /**
223     * Start preview mode.
224     *
225     * @return status The status code for this operation.
226     */
227    startPreview() generates (Status status);
228
229    /**
230     * Stop a previously started preview.
231     */
232    stopPreview();
233
234    /**
235     * Returns true if preview is enabled.
236     *
237     * @return enabled Whether preview is currently enabled.
238     */
239    previewEnabled() generates (bool enabled);
240
241    /**
242     * Request the camera HAL to store meta data or real YUV data in the video
243     * buffers sent out via CAMERA_MSG_VIDEO_FRAME for a recording session. If
244     * it is not called, the default camera HAL behavior is to store real YUV
245     * data in the video buffers.
246     *
247     * This method must be called before startRecording() in order to be
248     * effective.
249     *
250     * If meta data is stored in the video buffers, it is up to the receiver of
251     * the video buffers to interpret the contents and to find the actual frame
252     * data with the help of the meta data in the buffer. How this is done is
253     * outside of the scope of this method.
254     *
255     * Some camera HALs may not support storing meta data in the video buffers,
256     * but all camera HALs must support storing real YUV data in the video
257     * buffers. If the camera HAL does not support storing the meta data in the
258     * video buffers when it is requested to do do, INVALID_OPERATION must be
259     * returned. It is very useful for the camera HAL to pass meta data rather
260     * than the actual frame data directly to the video encoder, since the
261     * amount of the uncompressed frame data can be very large if video size is
262     * large.
263     *
264     * @param enable Set to true to instruct the camera HAL to store meta data
265     *     in the video buffers; false to instruct the camera HAL to store real
266     *     YUV data in the video buffers.
267     *
268     * @return status OK on success.
269     */
270    storeMetaDataInBuffers(bool enable) generates (Status status);
271
272    /**
273     * Start record mode.
274     *
275     * When a record image is available, a CAMERA_MSG_VIDEO_FRAME message is
276     * sent with the corresponding frame. Every record frame must be released by
277     * a camera HAL client via releaseRecordingFrame() before the client calls
278     * disableMsgType(CAMERA_MSG_VIDEO_FRAME). After the client calls
279     * disableMsgType(CAMERA_MSG_VIDEO_FRAME), it is the camera HAL's
280     * responsibility to manage the life-cycle of the video recording frames,
281     * and the client must not modify/access any video recording frames.
282     *
283     * @return status The status code for the operation.
284     */
285    startRecording() generates (Status status);
286
287    /**
288     * Stop a previously started recording.
289     */
290    stopRecording();
291
292    /**
293     * Returns true if recording is enabled.
294     *
295     * @return enabled True if recording is currently active.
296     */
297    recordingEnabled() generates (bool enabled);
298
299    /**
300     * Release a record frame previously returned by CAMERA_MSG_VIDEO_FRAME in
301     * dataCallbackTimestamp.
302     *
303     * It is camera HAL client's responsibility to release video recording
304     * frames sent out by the camera HAL before the camera HAL receives a call
305     * to disableMsgType(CAMERA_MSG_VIDEO_FRAME). After it receives the call to
306     * disableMsgType(CAMERA_MSG_VIDEO_FRAME), it is the camera HAL's
307     * responsibility to manage the life-cycle of the video recording frames.
308     *
309     * @param memId The memory buffer to release a recording frame from.
310     * @param bufferIndex The specific buffer index to return to the HAL.
311     */
312    releaseRecordingFrame(MemoryId memId, uint32_t bufferIndex);
313
314    /**
315     * Release a record frame previously returned by CAMERA_MSG_VIDEO_FRAME in
316     * handleCallbackTimestamp.
317     *
318     * It is camera HAL client's responsibility to release video recording
319     * frames sent out by the camera HAL before the camera HAL receives a call
320     * to disableMsgType(CAMERA_MSG_VIDEO_FRAME). After it receives the call to
321     * disableMsgType(CAMERA_MSG_VIDEO_FRAME), it is the camera HAL's
322     * responsibility to manage the life-cycle of the video recording frames.
323     *
324     * @param memId The memory buffer to release a recording frame from.
325     * @param bufferIndex The specific buffer index to return to the HAL.
326     * @param frame The handle for a released video frame
327     */
328    releaseRecordingFrameHandle(MemoryId memId, uint32_t bufferIndex, handle frame);
329
330    /**
331     * Release a batch of record frames previously returned by CAMERA_MSG_VIDEO_FRAME
332     * in handleCallbackTimestampBatch.
333     *
334     * It is camera HAL client's responsibility to release video recording
335     * frames sent out by the camera HAL before the camera HAL receives a call
336     * to disableMsgType(CAMERA_MSG_VIDEO_FRAME). After it receives the call to
337     * disableMsgType(CAMERA_MSG_VIDEO_FRAME), it is the camera HAL's
338     * responsibility to manage the life-cycle of the video recording frames.
339     *
340     * @param batch A batch of recording frames to be released by camera HAL.
341     */
342    releaseRecordingFrameHandleBatch(vec<VideoFrameMessage> batch);
343
344    /**
345     * Start auto focus.
346     *
347     * The notification callback routine is called with
348     * CAMERA_MSG_FOCUS once when focusing is complete. autoFocus() can be
349     * called again after that if another auto focus is needed.
350     *
351     * @return status The status code for this operation.
352     */
353    autoFocus() generates (Status status);
354
355    /**
356     * Cancels auto-focus function.
357     *
358     * If the auto-focus is still in progress, this function must cancel
359     * it. Whether the auto-focus is in progress or not, this function must
360     * return the focus position to the default. If the camera does not support
361     * auto-focus, this is a no-op.
362     *
363     * @return status The status code for this operation.
364     */
365    cancelAutoFocus() generates (Status status);
366
367    /**
368     * Take a picture.
369     *
370     * @return status The status code for this operation.
371     */
372    takePicture() generates (Status status);
373
374    /**
375     * Cancel a picture that was started with takePicture. Calling this method
376     * when no picture is being taken is a no-op.
377     *
378     * @return status The status code for this operation.
379     */
380    cancelPicture() generates (Status status);
381
382    /**
383     * Set the camera parameters.
384     *
385     * @param params The parameter string, consisting of
386     *    '<key1>=<value1>; ...;<keyN>=<valueN>'.
387     * @return status The status code for this operation:
388     *     OK: Parameter update was successful
389     *     ILLEGAL_ARGUMENT: At least one parameter was invalid or not supported
390     *
391     */
392    setParameters(string params) generates (Status status);
393
394    /**
395     * Retrieve the camera parameters.
396     */
397    getParameters() generates (string parms);
398
399    /**
400     * Send command to camera driver.
401     * The meaning of the arguments is defined by the value of cmd, documented
402     * in the CommandType definition.
403     *
404     * @param cmd The command to invoke.
405     * @param arg1 The first argument for the command, if needed.
406     * @param arg2 The second argument for the command, if needed.
407     *
408     * @return status The status code for this operation.
409     */
410    sendCommand(CommandType cmd, int32_t arg1, int32_t arg2)
411            generates (Status status);
412
413    /**
414     * Release the hardware resources owned by this object, shutting down the
415     * camera device.
416     */
417    close();
418
419};
420