1 /*
2  * Copyright 2023 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 
17 package androidx.camera.camera2.pipe
18 
19 import android.hardware.camera2.CaptureResult
20 import android.hardware.camera2.TotalCaptureResult
21 import androidx.annotation.RestrictTo
22 
23 /**
24  * A [FrameNumber] is the identifier that represents a specific exposure by the Camera. FrameNumbers
25  * increase within a specific CameraCaptureSession, and are not created until the HAL begins
26  * processing a request.
27  */
28 @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)
29 @JvmInline
30 public value class FrameNumber(public val value: Long)
31 
32 /** [FrameInfo] is a wrapper around [TotalCaptureResult]. */
33 @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)
34 public interface FrameInfo : UnsafeWrapper {
35     public val metadata: FrameMetadata
36 
37     /**
38      * If this [FrameInfo] was produced from a logical camera there will be metadata associated with
39      * the physical streams that were sent to the camera.
40      */
getnull41     public operator fun get(camera: CameraId): FrameMetadata?
42 
43     public val camera: CameraId
44     public val frameNumber: FrameNumber
45     public val requestMetadata: RequestMetadata
46 }
47 
48 /** [FrameMetadata] is a wrapper around [CaptureResult]. */
49 @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)
50 public interface FrameMetadata : Metadata, UnsafeWrapper {
51     public operator fun <T> get(key: CaptureResult.Key<T>): T?
52 
53     public fun <T> getOrDefault(key: CaptureResult.Key<T>, default: T): T
54 
55     public val camera: CameraId
56     public val frameNumber: FrameNumber
57 
58     /**
59      * Extra metadata will override values defined by the wrapped CaptureResult object. This is
60      * exposed separately to allow other systems to know what is altered relative to Camera2.
61      */
62     public val extraMetadata: Map<*, Any?>
63 }
64 
65 /**
66  * This defines a metadata transform that will be applied to the data produced by
67  * [Request.Listener.onTotalCaptureResult]. The returned map will override the values returned by
68  * TotalCaptureResult. Setting the offset and window size will cause the
69  * [Request.Listener.onComplete] method to be delayed so that the transform can be run on future
70  * metadata.
71  */
72 @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)
73 public data class MetadataTransform(
74     /**
75      * This defines the number of historical [TotalCaptureResult] objects this transform is allowed
76      * to look at. Setting this value to > 0 increases the number of [TotalCaptureResult] the
77      * [CameraGraph] will hold on to.
78      */
79     val past: Int = 0,
80 
81     /**
82      * This defines the number of future [TotalCaptureResult] objects this transform is allowed to
83      * look at. Setting this value to > 0 will cause [Request.Listener.onComplete] to be delayed by
84      * the number of frames specified here.
85      */
86     val future: Int = 0,
87 
88     /**
89      * This transform function will be invoked at high speed, and may be invoked multiple times if
90      * correcting physical camera results.
91      *
92      * the returned values should be limited to values that will override the default values that
93      * are set on the TotalCaptureResult for this frame.
94      */
95     val transformFn: TransformFn = object : TransformFn {}
96 ) {
97     init {
98         check(past >= 0)
99         check(future >= 0)
100     }
101 
102     @JvmDefaultWithCompatibility
103     public interface TransformFn {
computeOverridesFornull104         public fun computeOverridesFor(
105             result: FrameInfo,
106             camera: CameraId,
107             related: List<FrameInfo?>
108         ): Map<*, Any?> = emptyMap<Any, Any?>()
109     }
110 }
111