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.automotive.evs@1.0;
18
19import types;
20import IEvsCameraStream;
21
22
23/**
24 * Represents a single camera and is the primary interface for capturing images.
25 */
26interface IEvsCamera {
27
28    /**
29     * Returns the ID of this camera.
30     *
31     * Returns the description of this camera. This must be the same value as reported
32     * by EvsEnumerator::getCamerList().
33     */
34    getCameraInfo() generates (CameraDesc info);
35
36    /**
37     * Specifies the depth of the buffer chain the camera is asked to support.
38     *
39     * Up to this many frames may be held concurrently by the client of IEvsCamera.
40     * If this many frames have been delivered to the receiver without being returned
41     * by doneWithFrame, the stream must skip frames until a buffer is returned for reuse.
42     * It is legal for this call to come at any time, even while streams are already running,
43     * in which case buffers should be added or removed from the chain as appropriate.
44     * If no call is made to this entry point, the IEvsCamera must support at least one
45     * frame by default. More is acceptable.
46     * BUFFER_NOT_AVAILABLE is returned if the implementation cannot support the
47     * requested number of concurrent frames.
48     */
49    setMaxFramesInFlight(uint32_t bufferCount) generates (EvsResult result);
50
51    /**
52     * Request delivery of EVS camera frames from this camera.
53     *
54     * The IEvsCameraStream must begin receiving periodic calls with new image
55     * frames until stopVideoStream() is called.
56     */
57    startVideoStream(IEvsCameraStream receiver) generates (EvsResult result);
58
59    /**
60     * Return a frame that was delivered by to the IEvsCameraStream.
61     *
62     * When done consuming a frame delivered to the IEvsCameraStream
63     * interface, it must be returned to the IEvsCamera for reuse.
64     * A small, finite number of buffers are available (possibly as small
65     * as one), and if the supply is exhausted, no further frames may be
66     * delivered until a buffer is returned.
67     */
68    oneway doneWithFrame(BufferDesc buffer);
69
70    /**
71     * Stop the delivery of EVS camera frames.
72     *
73     * Because delivery is asynchronous, frames may continue to arrive for
74     * some time after this call returns. Each must be returned until the
75     * closure of the stream is signaled to the IEvsCameraStream.
76     * This function cannot fail and is simply ignored if the stream isn't running.
77     */
78    stopVideoStream();
79
80    /**
81     * Request driver specific information from the HAL implementation.
82     *
83     * The values allowed for opaqueIdentifier are driver specific,
84     * but no value passed in may crash the driver. The driver should
85     * return 0 for any unrecognized opaqueIdentifier.
86     */
87    getExtendedInfo(uint32_t opaqueIdentifier) generates (int32_t value);
88
89    /**
90     * Send a driver specific value to the HAL implementation.
91     *
92     * This extension is provided to facilitate car specific
93     * extensions, but no HAL implementation may require this call
94     * in order to function in a default state.
95     * INVALID_ARG is returned if the opaqueValue is not meaningful to
96     * the driver implementation.
97     */
98    setExtendedInfo(uint32_t opaqueIdentifier, int32_t opaqueValue) generates (EvsResult result);
99};
100