1 /* 2 * Copyright (C) 2024 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 android.hardware.camera2; 18 19 import android.annotation.FlaggedApi; 20 import android.annotation.NonNull; 21 import android.hardware.camera2.CaptureRequest; 22 import android.hardware.camera2.CaptureRequest.Key; 23 import android.hardware.camera2.impl.ExtensionKey; 24 import android.hardware.camera2.impl.PublicKey; 25 26 import com.android.internal.camera.flags.Flags; 27 28 /** 29 * ExtensionCaptureRequest contains definitions for extension-specific CaptureRequest keys that 30 * can be used to configure a {@link android.hardware.camera2.CaptureRequest} during a 31 * {@link android.hardware.camera2.CameraExtensionSession}. 32 * 33 * Note that ExtensionCaptureRequest is not intended to be used as a replacement 34 * for CaptureRequest in the extensions. It serves as a supplementary class providing 35 * extension-specific CaptureRequest keys. Developers should use these keys in conjunction 36 * with regular CaptureRequest objects during a 37 * {@link android.hardware.camera2.CameraExtensionSession}. 38 * 39 * @see CaptureRequest 40 * @see CameraExtensionSession 41 */ 42 @FlaggedApi(Flags.FLAG_CONCERT_MODE_API) 43 public final class ExtensionCaptureRequest { 44 45 /** To avoid exposing constructor */ ExtensionCaptureRequest()46 private ExtensionCaptureRequest() {} 47 48 /** 49 * <p>Used to apply an additional digital zoom factor for the 50 * {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY } 51 * extension in {@link android.hardware.camera2.ExtensionCaptureRequest#EFV_STABILIZATION_MODE_LOCKED } mode.</p> 52 * <p>For the {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY } 53 * feature, an additional zoom factor is applied on top of the existing {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio}. 54 * This additional zoom factor serves as a buffer to provide more flexibility for the 55 * {@link android.hardware.camera2.ExtensionCaptureRequest#EFV_STABILIZATION_MODE_LOCKED } 56 * mode. If {@link ExtensionCaptureRequest#EFV_PADDING_ZOOM_FACTOR } is not set, the default will be used. 57 * The effectiveness of the stabilization may be influenced by the amount of padding zoom 58 * applied. A higher padding zoom factor can stabilize the target region more effectively 59 * with greater flexibility but may potentially impact image quality. Conversely, a lower 60 * padding zoom factor may be used to prioritize preserving image quality, albeit with less 61 * leeway in stabilizing the target region. It is recommended to set the 62 * {@link android.hardware.camera2.ExtensionCaptureRequest#EFV_PADDING_ZOOM_FACTOR } to at least 1.5.</p> 63 * <p>If {@link ExtensionCaptureRequest#EFV_AUTO_ZOOM } is enabled, the requested {@link ExtensionCaptureRequest#EFV_PADDING_ZOOM_FACTOR } will be overridden. 64 * {@link ExtensionCaptureRequest#EFV_MAX_PADDING_ZOOM_FACTOR } can be checked for more details on controlling the 65 * padding zoom factor during {@link ExtensionCaptureRequest#EFV_AUTO_ZOOM }.</p> 66 * <p><b>Range of valid values:</b><br> 67 * {@link CameraExtensionCharacteristics#EFV_PADDING_ZOOM_FACTOR_RANGE }</p> 68 * <p><b>Optional</b> - The value for this key may be {@code null} on some devices.</p> 69 * 70 * @see CaptureRequest#CONTROL_ZOOM_RATIO 71 * @see ExtensionCaptureRequest#EFV_AUTO_ZOOM 72 * @see ExtensionCaptureRequest#EFV_MAX_PADDING_ZOOM_FACTOR 73 * @see ExtensionCaptureRequest#EFV_PADDING_ZOOM_FACTOR 74 * @see CameraExtensionCharacteristics#EFV_PADDING_ZOOM_FACTOR_RANGE 75 */ 76 @PublicKey 77 @NonNull 78 @ExtensionKey 79 @FlaggedApi(Flags.FLAG_CONCERT_MODE_API) 80 public static final Key<Float> EFV_PADDING_ZOOM_FACTOR = CaptureRequest.EFV_PADDING_ZOOM_FACTOR; 81 82 /** 83 * <p>Used to enable or disable auto zoom for the 84 * {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY } 85 * extension in {@link android.hardware.camera2.ExtensionCaptureRequest#EFV_STABILIZATION_MODE_LOCKED } mode.</p> 86 * <p>Turn on auto zoom to let the 87 * {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY } 88 * feature decide at any given point a combination of 89 * {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio} and {@link ExtensionCaptureRequest#EFV_PADDING_ZOOM_FACTOR } 90 * to keep the target region in view and stabilized. The combination chosen by the 91 * {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY } 92 * will equal the requested {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio} multiplied with the requested 93 * {@link ExtensionCaptureRequest#EFV_PADDING_ZOOM_FACTOR }. A limit can be set on the padding zoom if wanting 94 * to control image quality further using {@link ExtensionCaptureRequest#EFV_MAX_PADDING_ZOOM_FACTOR }.</p> 95 * <p><b>Optional</b> - The value for this key may be {@code null} on some devices.</p> 96 * 97 * @see CaptureRequest#CONTROL_ZOOM_RATIO 98 * @see ExtensionCaptureRequest#EFV_MAX_PADDING_ZOOM_FACTOR 99 * @see ExtensionCaptureRequest#EFV_PADDING_ZOOM_FACTOR 100 */ 101 @PublicKey 102 @NonNull 103 @ExtensionKey 104 @FlaggedApi(Flags.FLAG_CONCERT_MODE_API) 105 public static final Key<Boolean> EFV_AUTO_ZOOM = CaptureRequest.EFV_AUTO_ZOOM; 106 107 /** 108 * <p>Used to limit the {@link ExtensionCaptureRequest#EFV_PADDING_ZOOM_FACTOR } if 109 * {@link ExtensionCaptureRequest#EFV_AUTO_ZOOM } is enabled for the 110 * {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY } 111 * extension in {@link android.hardware.camera2.ExtensionCaptureRequest#EFV_STABILIZATION_MODE_LOCKED } mode.</p> 112 * <p>If {@link ExtensionCaptureRequest#EFV_AUTO_ZOOM } is enabled, this key can be used to set a limit 113 * on the {@link ExtensionCaptureRequest#EFV_PADDING_ZOOM_FACTOR } chosen by the 114 * {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY } 115 * extension in {@link android.hardware.camera2.ExtensionCaptureRequest#EFV_STABILIZATION_MODE_LOCKED } mode 116 * to control image quality.</p> 117 * <p><b>Range of valid values:</b><br> 118 * The range of {@link CameraExtensionCharacteristics#EFV_PADDING_ZOOM_FACTOR_RANGE Range}. Use a value greater than or equal to 119 * the {@link android.hardware.camera2.ExtensionCaptureRequest#EFV_PADDING_ZOOM_FACTOR } to 120 * effectively utilize this key.</p> 121 * <p><b>Optional</b> - The value for this key may be {@code null} on some devices.</p> 122 * 123 * @see ExtensionCaptureRequest#EFV_AUTO_ZOOM 124 * @see ExtensionCaptureRequest#EFV_PADDING_ZOOM_FACTOR 125 * @see CameraExtensionCharacteristics#EFV_PADDING_ZOOM_FACTOR_RANGE 126 */ 127 @PublicKey 128 @NonNull 129 @ExtensionKey 130 @FlaggedApi(Flags.FLAG_CONCERT_MODE_API) 131 public static final Key<Float> EFV_MAX_PADDING_ZOOM_FACTOR = CaptureRequest.EFV_MAX_PADDING_ZOOM_FACTOR; 132 133 /** 134 * <p>Set the stabilization mode for the 135 * {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY } 136 * extension</p> 137 * <p>The desired stabilization mode. Gimbal stabilization mode provides simple, non-locked 138 * video stabilization. Locked mode uses the 139 * {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY } 140 * stabilization feature to fixate on the current region, utilizing it as the target area for 141 * stabilization.</p> 142 * <p><b>Possible values:</b></p> 143 * <ul> 144 * <li>{@link #EFV_STABILIZATION_MODE_OFF OFF}</li> 145 * <li>{@link #EFV_STABILIZATION_MODE_GIMBAL GIMBAL}</li> 146 * <li>{@link #EFV_STABILIZATION_MODE_LOCKED LOCKED}</li> 147 * </ul> 148 * 149 * <p><b>Optional</b> - The value for this key may be {@code null} on some devices.</p> 150 * @see #EFV_STABILIZATION_MODE_OFF 151 * @see #EFV_STABILIZATION_MODE_GIMBAL 152 * @see #EFV_STABILIZATION_MODE_LOCKED 153 */ 154 @PublicKey 155 @NonNull 156 @ExtensionKey 157 @FlaggedApi(Flags.FLAG_CONCERT_MODE_API) 158 public static final Key<Integer> EFV_STABILIZATION_MODE = CaptureRequest.EFV_STABILIZATION_MODE; 159 160 /** 161 * <p>Used to update the target region for the 162 * {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY } 163 * extension in {@link android.hardware.camera2.ExtensionCaptureRequest#EFV_STABILIZATION_MODE_LOCKED } mode.</p> 164 * <p>A android.util.Pair<Integer,Integer> that represents the desired 165 * <Horizontal,Vertical> shift of the current locked view (or target region) in 166 * pixels. Negative values indicate left and upward shifts, while positive values indicate 167 * right and downward shifts in the active array coordinate system.</p> 168 * <p><b>Range of valid values:</b><br> 169 * android.util.Pair<Integer,Integer> represents the 170 * <Horizontal,Vertical> shift. The range for the horizontal shift is 171 * [-max({@link ExtensionCaptureResult#EFV_PADDING_REGION }-left), max({@link ExtensionCaptureResult#EFV_PADDING_REGION }-right)]. 172 * The range for the vertical shift is 173 * [-max({@link ExtensionCaptureResult#EFV_PADDING_REGION }-top), max({@link ExtensionCaptureResult#EFV_PADDING_REGION }-bottom)]</p> 174 * <p><b>Optional</b> - The value for this key may be {@code null} on some devices.</p> 175 * 176 * @see ExtensionCaptureResult#EFV_PADDING_REGION 177 */ 178 @PublicKey 179 @NonNull 180 @ExtensionKey 181 @FlaggedApi(Flags.FLAG_CONCERT_MODE_API) 182 public static final Key<android.util.Pair<Integer,Integer>> EFV_TRANSLATE_VIEWPORT = CaptureRequest.EFV_TRANSLATE_VIEWPORT; 183 184 /** 185 * <p>Representing the desired clockwise rotation 186 * of the target region in degrees for the 187 * {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY } 188 * extension in {@link android.hardware.camera2.ExtensionCaptureRequest#EFV_STABILIZATION_MODE_LOCKED } mode.</p> 189 * <p>Value representing the desired clockwise rotation of the target 190 * region in degrees.</p> 191 * <p><b>Range of valid values:</b><br> 192 * 0 to 360</p> 193 * <p><b>Optional</b> - The value for this key may be {@code null} on some devices.</p> 194 */ 195 @PublicKey 196 @NonNull 197 @ExtensionKey 198 @FlaggedApi(Flags.FLAG_CONCERT_MODE_API) 199 public static final Key<Float> EFV_ROTATE_VIEWPORT = CaptureRequest.EFV_ROTATE_VIEWPORT; 200 201 202 // 203 // Enumeration values for CaptureRequest#EFV_STABILIZATION_MODE 204 // 205 206 /** 207 * <p>No stabilization.</p> 208 * @see ExtensionCaptureRequest#EFV_STABILIZATION_MODE 209 */ 210 @FlaggedApi(Flags.FLAG_CONCERT_MODE_API) 211 public static final int EFV_STABILIZATION_MODE_OFF = CaptureRequest.EFV_STABILIZATION_MODE_OFF; 212 213 /** 214 * <p>Gimbal stabilization mode.</p> 215 * @see ExtensionCaptureRequest#EFV_STABILIZATION_MODE 216 */ 217 @FlaggedApi(Flags.FLAG_CONCERT_MODE_API) 218 public static final int EFV_STABILIZATION_MODE_GIMBAL = CaptureRequest.EFV_STABILIZATION_MODE_GIMBAL; 219 220 /** 221 * <p>Locked stabilization mode which uses the 222 * {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY } 223 * stabilization to directionally steady the target region.</p> 224 * @see ExtensionCaptureRequest#EFV_STABILIZATION_MODE 225 */ 226 @FlaggedApi(Flags.FLAG_CONCERT_MODE_API) 227 public static final int EFV_STABILIZATION_MODE_LOCKED = CaptureRequest.EFV_STABILIZATION_MODE_LOCKED; 228 229 } 230