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.common@1.0;
18
19/**
20 * Common enumeration and structure definitions for all HALs under
21 * android.hardware.camera
22 */
23
24/**
25 * Status codes for camera HAL method calls.
26 *
27 */
28enum Status : uint32_t {
29    /**
30     * Method call succeeded
31     */
32    OK = 0,
33
34    /**
35     * One of the arguments to the method call is invalid. For example,
36     * the camera ID is unknown.
37     */
38    ILLEGAL_ARGUMENT = 1,
39
40    /**
41     * The specified camera device is already in use
42     */
43    CAMERA_IN_USE = 2,
44
45    /**
46     * The HAL cannot support more simultaneous cameras in use.
47     */
48    MAX_CAMERAS_IN_USE = 3,
49
50    /**
51     * This HAL does not support this method.
52     */
53    METHOD_NOT_SUPPORTED = 4,
54
55    /**
56     * The specified camera device does not support this operation.
57     */
58    OPERATION_NOT_SUPPORTED = 5,
59
60    /**
61     * This camera device is no longer connected or otherwise available for use
62     */
63    CAMERA_DISCONNECTED = 6,
64
65    /**
66     * The HAL has encountered an internal error and cannot complete the
67     * request.
68     */
69    INTERNAL_ERROR = 7
70};
71
72/**
73 * Possible states that the flash unit on a closed camera device can be set to
74 * via the ICameraProvider::setTorchMode() method.
75 */
76enum TorchMode : uint32_t {
77    OFF = 0, // Turn off the flash
78    ON  = 1  // Turn on the flash to torch mode
79};
80
81/**
82 * Camera metadata type - duplicated from VNDK libcamera_metadata for vendor tag
83 * definitions.
84 */
85enum CameraMetadataType : uint32_t {
86    // Unsigned 8-bit integer (uint8_t)
87    BYTE = 0,
88    // Signed 32-bit integer (int32_t)
89    INT32 = 1,
90    // 32-bit float (float)
91    FLOAT = 2,
92    // Signed 64-bit integer (int64_t)
93    INT64 = 3,
94    // 64-bit float (double)
95    DOUBLE = 4,
96    // A 64-bit fraction (camera_metadata_rational_t)
97    RATIONAL = 5
98};
99
100/**
101 * A single vendor-unique metadata tag.
102 * The full name of the tag is <sectionName>.<tagName>
103 */
104struct VendorTag {
105    uint32_t tagId; // Tag identifier, must be >= TagBoundaryId::VENDOR
106    string tagName; // Name of tag, not including section name
107    CameraMetadataType tagType;
108};
109
110/**
111 * A set of related vendor tags.
112 */
113struct VendorTagSection {
114    string sectionName; // Section name; must be namespaced within vendor's name
115    vec<VendorTag> tags; // List of tags in this section
116};
117
118enum TagBoundaryId : uint32_t {
119    AOSP    = 0x0,         // First valid tag id for android-defined tags
120    VENDOR  = 0x80000000u  // First valid tag id for vendor extension tags
121};
122
123/**
124 * CameraDeviceStatus
125 *
126 * The current status of a camera device, as sent by a camera provider HAL
127 * through the ICameraProviderCallback::cameraDeviceStatusChange() call.
128 *
129 * At startup, the camera service must assume all internal camera devices listed
130 * by ICameraProvider::getCameraIdList() are in the PRESENT state. The provider
131 * must invoke ICameraProviderCallback::cameraDeviceStatusChange to inform the
132 * service of any initially NOT_PRESENT internal devices, and of any PRESENT
133 * external camera devices, as soon as the camera service has called
134 * ICameraProvider::setCallback().
135 *
136 * Allowed state transitions:
137 *      PRESENT            -> NOT_PRESENT
138 *      NOT_PRESENT        -> ENUMERATING
139 *      NOT_PRESENT        -> PRESENT
140 *      ENUMERATING        -> PRESENT
141 *      ENUMERATING        -> NOT_PRESENT
142 */
143enum CameraDeviceStatus : uint32_t {
144    /**
145     * The camera device is not currently connected, and trying to reference it
146     * in provider method calls must return status code ILLEGAL_ARGUMENT.
147     *
148     */
149    NOT_PRESENT = 0,
150
151    /**
152     * The camera device is connected, and opening it is possible, as long as
153     * sufficient resources are available.
154     *
155     * By default, the framework must assume all devices returned by
156     * ICameraProvider::getCameraIdList() are in this state.
157     */
158    PRESENT = 1,
159
160    /**
161     * The camera device is connected, but it is undergoing enumeration and
162     * startup, and so opening the device must return CAMERA_IN_USE.
163     *
164     * Attempting to call ICameraProvider::getCameraCharacteristics() must
165     * succeed, however.
166     */
167    ENUMERATING = 2,
168
169};
170
171/**
172 * TorchModeStatus:
173 *
174 * The current status of the torch mode on a given camera device, sent by a
175 * camera provider HAL via the ICameraProviderCallback::TorchModeStatusChange()
176 * call.
177 *
178 * The torch mode status of a camera device is applicable only when the camera
179 * device is present. The camera service must not call
180 * ICameraProvider::setTorchMode() to turn on torch mode of a camera device if
181 * the camera device is not present. At camera service startup time, the
182 * framework must assume torch modes are in the AVAILABLE_OFF state if the
183 * camera device is present and the camera characteristics entry
184 * android.flash.info.available is reported as true via
185 * ICameraProvider::getCameraCharacteristics() call. The same is assumed for
186 * external camera devices when they are initially connected.
187 *
188 * The camera service requires the following behaviors from the camera provider
189 * HAL when a camera device's status changes:
190 *
191 *  1. A previously-disconnected camera device becomes connected. After
192 *      ICameraProviderCallback::CameraDeviceStatusChange() is invoked to inform
193 *      the camera service that the camera device is present, the framework must
194 *      assume the camera device's torch mode is in AVAILABLE_OFF state if it
195 *      has a flash unit. The camera provider HAL does not need to invoke
196 *      ICameraProviderCallback::TorchModeStatusChange() unless the flash unit
197 *      is unavailable to use by ICameraProvider::setTorchMode().
198 *
199 *  2. A previously-connected camera becomes disconnected. After
200 *      ICameraProviderCallback::CameraDeviceStatusChange() is invoked to inform
201 *      the camera service that the camera device is not present, the framework
202 *      must not call ICameraProvider::setTorchMode() for the disconnected camera
203 *      device until it is connected again. The camera provider HAL does not
204 *      need to invoke ICameraProviderCallback::TorchModeStatusChange()
205 *      separately to inform that the flash unit has become NOT_AVAILABLE.
206 *
207 *  3. openCameraDevice() or openCameraDeviceVersion() is called to open a
208 *      camera device. The camera provider HAL must invoke
209 *      ICameraProviderCallback::TorchModeStatusChange() for all flash units
210 *      that have entered NOT_AVAILABLE state and can not be turned on by
211 *      calling ICameraProvider::setTorchMode() due to this open() call.
212 *      openCameraDevice() must not trigger AVAILABLE_OFF before NOT_AVAILABLE
213 *      for all flash units that have become unavailable.
214 *
215 *  4. ICameraDevice.close() is called to close a camera device. The camera
216 *      provider HAL must call ICameraProviderCallback::torchModeStatusChange()
217 *      for all flash units that have now entered the AVAILABLE_OFF state and
218 *      can be turned on by calling ICameraProvider::setTorchMode() again because
219 *      of sufficient new camera resources being freed up by this close() call.
220 *
221 *  Note that the camera service calling ICameraProvider::setTorchMode()
222 *  successfully must trigger AVAILABLE_OFF or AVAILABLE_ON callback for the
223 *  given camera device. Additionally it must trigger AVAILABLE_OFF callbacks
224 *  for other previously-on torch modes if HAL cannot keep multiple devices'
225 *  flashlights on simultaneously.
226 */
227enum TorchModeStatus : uint32_t {
228    /**
229     * The flash unit is no longer available and the torch mode can not be
230     * turned on by calling setTorchMode(). If the torch mode was AVAILABLE_ON,
231     * the flashlight must be turned off by the provider HAL before the provider
232     * HAL calls torchModeStatusChange().
233     */
234    NOT_AVAILABLE = 0,
235
236    /**
237     * A torch mode has become off and is available to be turned on via
238     * ICameraProvider::setTorchMode(). This may happen in the following
239     * cases:
240     *   1. After the resources to turn on the torch mode have become available.
241     *   2. After ICameraProvider::setTorchMode() is called to turn off the torch
242     *      mode.
243     *   3. After the camera service turned on the torch mode for some other
244     *      camera device and the provider HAL had to turn off the torch modes
245     *      of other camera device(s) that were previously on, due to lack of
246     *      resources to keep them all on.
247     */
248    AVAILABLE_OFF = 1,
249
250    /**
251     * A torch mode has become on and is available to be turned off via
252     * ICameraProvider::setTorchMode(). This can happen only after
253     * ICameraProvider::setTorchMode() has been called to turn on the torch mode.
254     */
255    AVAILABLE_ON = 2,
256
257};
258
259/**
260 * CameraResourceCost:
261 *
262 * Structure defining the abstract resource cost of opening a camera device,
263 * and any usage conflicts between multiple camera devices.
264 *
265 * Obtainable via ICameraDevice::getResourceCost()
266 */
267struct CameraResourceCost {
268    /**
269     * The total resource "cost" of using this camera, represented as an integer
270     * value in the range [0, 100] where 100 represents total usage of the
271     * shared resource that is the limiting bottleneck of the camera subsystem.
272     * This may be a very rough estimate, and is used as a hint to the camera
273     * service to determine when to disallow multiple applications from
274     * simultaneously opening different cameras advertised by the camera
275     * service.
276     *
277     * The camera service must be able to simultaneously open and use any
278     * combination of camera devices exposed by the HAL where the sum of
279     * the resource costs of these cameras is <= 100. For determining cost,
280     * each camera device must be assumed to be configured and operating at
281     * the maximally resource-consuming framerate and stream size settings
282     * available in the configuration settings exposed for that device through
283     * the camera metadata.
284     *
285     * The camera service may still attempt to simultaneously open combinations
286     * of camera devices with a total resource cost > 100. This may succeed or
287     * fail. If this succeeds, combinations of configurations that are not
288     * supported due to resource constraints from having multiple open devices
289     * must fail during the configure calls. If the total resource cost is <=
290     * 100, open and configure must never fail for any stream configuration
291     * settings or other device capabilities that would normally succeed for a
292     * device when it is the only open camera device.
293     *
294     * This field may be used to determine whether background applications are
295     * allowed to use this camera device while other applications are using
296     * other camera devices. Note: multiple applications must never be allowed
297     * by the camera service to simultaneously open the same camera device.
298     *
299     * Example use cases:
300     *
301     * Ex. 1: Camera Device 0 = Back Camera
302     *        Camera Device 1 = Front Camera
303     *   - Using both camera devices causes a large framerate slowdown due to
304     *     limited ISP bandwidth.
305     *
306     *   Configuration:
307     *
308     *   Camera Device 0 - resourceCost = 51
309     *                     conflicting_devices = empty
310     *   Camera Device 1 - resourceCost = 51
311     *                     conflicting_devices = empty
312     *
313     *   Result:
314     *
315     *   Since the sum of the resource costs is > 100, if a higher-priority
316     *   application has either device open, no lower-priority applications must
317     *   be allowed by the camera service to open either device. If a
318     *   lower-priority application is using a device that a higher-priority
319     *   subsequently attempts to open, the lower-priority application must be
320     *   forced to disconnect the the device.
321     *
322     *   If the highest-priority application chooses, it may still attempt to
323     *   open both devices (since these devices are not listed as conflicting in
324     *   the conflicting_devices fields), but usage of these devices may fail in
325     *   the open or configure calls.
326     *
327     * Ex. 2: Camera Device 0 = Left Back Camera
328     *        Camera Device 1 = Right Back Camera
329     *        Camera Device 2 = Combined stereo camera using both right and left
330     *                          back camera sensors used by devices 0, and 1
331     *        Camera Device 3 = Front Camera
332     *   - Due to do hardware constraints, up to two cameras may be open at
333     *     once. The combined stereo camera may never be used at the same time
334     *     as either of the two back camera devices (device 0, 1), and typically
335     *     requires too much bandwidth to use at the same time as the front
336     *     camera (device 3).
337     *
338     *   Configuration:
339     *
340     *   Camera Device 0 - resourceCost = 50
341     *                     conflicting_devices = { 2 }
342     *   Camera Device 1 - resourceCost = 50
343     *                     conflicting_devices = { 2 }
344     *   Camera Device 2 - resourceCost = 100
345     *                     conflicting_devices = { 0, 1 }
346     *   Camera Device 3 - resourceCost = 50
347     *                     conflicting_devices = empty
348     *
349     *   Result:
350     *
351     *   Based on the conflicting_devices fields, the camera service guarantees
352     *   that the following sets of open devices must never be allowed: { 1, 2
353     *   }, { 0, 2 }.
354     *
355     *   Based on the resourceCost fields, if a high-priority foreground
356     *   application is using camera device 0, a background application would be
357     *   allowed to open camera device 1 or 3 (but would be forced to disconnect
358     *   it again if the foreground application opened another device).
359     *
360     *   The highest priority application may still attempt to simultaneously
361     *   open devices 0, 2, and 3, but the HAL may fail in open or configure
362     *   calls for this combination.
363     *
364     * Ex. 3: Camera Device 0 = Back Camera
365     *        Camera Device 1 = Front Camera
366     *        Camera Device 2 = Low-power Front Camera that uses the same sensor
367     *                          as device 1, but only exposes image stream
368     *                          resolutions that can be used in low-power mode
369     *  - Using both front cameras (device 1, 2) at the same time is impossible
370     *    due a shared physical sensor. Using the back and "high-power" front
371     *    camera (device 1) may be impossible for some stream configurations due
372     *    to hardware limitations, but the "low-power" front camera option may
373     *    always be used as it has special dedicated hardware.
374     *
375     *   Configuration:
376     *
377     *   Camera Device 0 - resourceCost = 100
378     *                     conflicting_devices = empty
379     *   Camera Device 1 - resourceCost = 100
380     *                     conflicting_devices = { 2 }
381     *   Camera Device 2 - resourceCost = 0
382     *                     conflicting_devices = { 1 }
383     *   Result:
384     *
385     *   Based on the conflicting_devices fields, the camera service guarantees
386     *   that the following sets of open devices must never be allowed:
387     *   { 1, 2 }.
388     *
389     *   Based on the resourceCost fields, only the highest priority application
390     *   may attempt to open both device 0 and 1 at the same time. If a
391     *   higher-priority application is not using device 1 or 2, a low-priority
392     *   background application may open device 2 (but must be forced to
393     *   disconnect it if a higher-priority application subsequently opens
394     *   device 1 or 2).
395     */
396    uint32_t resourceCost;
397
398    /**
399     * An array of camera device IDs indicating other devices that cannot be
400     * simultaneously opened while this camera device is in use.
401     *
402     * This field is intended to be used to indicate that this camera device
403     * is a composite of several other camera devices, or otherwise has
404     * hardware dependencies that prohibit simultaneous usage. If there are no
405     * dependencies, an empty list may be returned to indicate this.
406     *
407     * The camera service must never simultaneously open any of the devices
408     * in this list while this camera device is open.
409     *
410     */
411    vec<string> conflictingDevices;
412
413};
414