1/*
2 * Copyright (C) 2020 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.provider@2.6;
18
19import @2.5::ICameraProvider;
20import android.hardware.camera.common@1.0::Status;
21import android.hardware.camera.device@3.4::StreamConfiguration;
22
23/**
24 * Camera provider HAL
25 *
26 * @2.6::adds support for the getConcurrentStreamingCameraIds() and
27 * isConcurrentStreamCombinationSupported()
28 * @2.6::ICameraProviderCallback to receive physical camera availability
29 * callbacks for logical multi-cameras.
30 */
31interface ICameraProvider extends @2.5::ICameraProvider {
32    /**
33     * getConcurrentStreamingCameraIds
34     *
35     * Get a vector of combinations of camera device ids that are able to
36     * configure streams concurrently. Each camera device advertised in a
37     * combination MUST at the very least support the following streams while
38     * streaming concurrently with the other camera ids in the combination.
39     *
40     *       Target 1                  Target 2
41     * -----------------------------------------------------
42     * | Type         |   Size   |   Type       |   Size   |
43     * -----------------------------------------------------
44     * | YUV          |  s1440p  |                         |
45     * -----------------------------------------------------
46     * | JPEG         |  s1440p  |                         |
47     * -----------------------------------------------------
48     * | PRIV         |  s1440p  |                         |
49     * -----------------------------------------------------
50     * | YUV / PRIV   |  s720p   |  YUV / PRIV   | s1440p  |
51     * -----------------------------------------------------
52     * | YUV / PRIV   |  s720p   |  JPEG         | s1440p  |
53     * -----------------------------------------------------
54     *
55     * where:
56     * s720p - min (max output resolution for the given format, 1280 X 720)
57     * s1440p - min (max output resolution for the given format, 1920 X 1440)
58     *
59     * If a device has MONOCHROME capability (device's capabilities include
60     * ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MONOCHROME) and therefore supports Y8
61     * outputs, stream combinations mentioned above, where YUV is substituted by
62     * Y8 must be also supported.
63     *
64     * Devices whose capabilities do not include
65     * ANDROID_REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE, must support
66     * at least a single Y16 stream, Dataspace::DEPTH with sVGA resolution,
67     * during concurrent operation.
68     * Where sVGA -  min (max output resolution for the given format, 640 X 480)
69     *
70     * The camera framework must call this method whenever it gets a
71     * cameraDeviceStatusChange callback adding a new camera device or removing
72     * a camera device known to it. This is so that the camera framework can get new combinations
73     * of camera ids that can stream concurrently, that might have potentially appeared.
74     *
75     * For each combination (and their subsets) of camera device ids returned by
76     * getConcurrentStreamingCameraIds(): If only the mandatory combinations can
77     * be supported concurrently by each device, then the resource costs must
78     * sum up to > 100 for the concurrent set, to ensure arbitration between
79     * camera applications work as expected. Only if resources are sufficient
80     * to run a set of cameras at full capability (maximally
81     * resource-consuming framerate and stream size settings available in the
82     * configuration settings exposed through camera metadata), should the sum
83     * of resource costs for the combination be <= 100.
84     *
85     * For guaranteed concurrent camera operation, the camera framework must call
86     * ICameraDevice.open() on all devices (intended for concurrent operation), before configuring
87     * any streams on them. This gives the camera HAL process an opportunity to potentially
88     * distribute hardware resources better before stream configuration.
89     *
90     * Due to potential hardware constraints around internal switching of physical camera devices,
91     * a device's complete ZOOM_RATIO_RANGE(if supported), may not apply during concurrent
92     * operation. If ZOOM_RATIO is supported, camera HALs must ensure ZOOM_RATIO_RANGE of
93     * [1.0, ANDROID_SCALER_AVAILABLE_MAX_DIGITAL_ZOOM] is supported by that device, during
94     * concurrent operation.
95     *
96     * @return status Status code for the operation
97     * @return cameraIds a list of camera id combinations that support
98     *         concurrent stream configurations with the minimum guarantees
99     *         specified.
100     */
101    getConcurrentStreamingCameraIds() generates (Status status, vec<vec<string>> cameraIds);
102
103    /**
104     * isConcurrentStreamCombinationSupported:
105     *
106     * Check for device support of specific camera stream combinations while
107     * streaming concurrently with other devices.
108     *
109     * The per device streamList must contain at least one output-capable stream, and may
110     * not contain more than one input-capable stream.
111     * In contrast to regular stream configuration the framework does not create
112     * or initialize any actual streams. This means that Hal must not use or
113     * consider the stream "id" value.
114     *
115     * ------------------------------------------------------------------------
116     *
117     * Preconditions:
118     *
119     * The framework can call this method at any time before, during and
120     * after active session configuration per device. This means that calls must not
121     * impact the performance of pending camera requests in any way. In
122     * particular there must not be any glitches or delays during normal
123     * camera streaming.
124     *
125     * The framework must not call this method with any combination of camera
126     * ids that is not a subset of the camera ids advertised by getConcurrentStreamingCameraIds of
127     * the same provider.
128     *
129     * Performance requirements:
130     * This call is expected to be significantly faster than stream
131     * configuration. In general HW and SW camera settings must not be
132     * changed and there must not be a user-visible impact on camera performance.
133     *
134     * @param configs a vector of camera ids and their corresponding stream
135     *                configurations that need to be queried for support.
136     *
137     * @return status Status code for the operation, one of:
138     *     OK:
139     *          On successful stream combination query.
140     *     METHOD_NOT_SUPPORTED:
141     *          The camera provider does not support stream combination query.
142     *     INTERNAL_ERROR:
143     *          The stream combination query cannot complete due to internal
144     *          error.
145     * @return true in case the stream combination is supported, false otherwise.
146     *
147     *
148     */
149    isConcurrentStreamCombinationSupported(vec<CameraIdAndStreamCombination> configs)
150        generates (Status status, bool queryStatus);
151};
152