1 /*
2  * Copyright 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 
17 package androidx.camera.core.impl;
18 
19 import android.graphics.ImageFormat;
20 
21 import androidx.camera.core.Camera;
22 import androidx.camera.core.DynamicRange;
23 import androidx.core.util.Preconditions;
24 
25 import org.jspecify.annotations.NonNull;
26 
27 /** Configuration containing options for configuring the input image data of a pipeline. */
28 public interface ImageInputConfig extends ReadableConfig {
29     Config.Option<Integer> OPTION_INPUT_FORMAT =
30             Config.Option.create("camerax.core.imageInput.inputFormat", int.class);
31     Config.Option<Integer> OPTION_SECONDARY_INPUT_FORMAT =
32             Config.Option.create("camerax.core.imageInput.secondaryInputFormat", int.class);
33     Config.Option<DynamicRange> OPTION_INPUT_DYNAMIC_RANGE =
34             Config.Option.create("camerax.core.imageInput.inputDynamicRange",
35                     DynamicRange.class);
36 
37     /**
38      * Retrieve the input image format.
39      *
40      * <p>This is the format that is required as input and it must be satisfied by the producer.
41      * It is used to determine if the producer, such as a {@link Camera} can actually support the
42      * {@link android.view.Surface}.
43      *
44      * <p>Except for ImageFormat.JPEG or ImageFormat.YUV, other image formats like SurfaceTexture or
45      * MediaCodec classes will be mapped to internal format HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED
46      * (0x22) in StreamConfigurationMap.java. 0x22 is also the code for ImageFormat.PRIVATE. But
47      * there is no ImageFormat.PRIVATE supported before Android level 23. There is same internal
48      * code 0x22 for internal corresponding format HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED.
49      * Therefore, setting 0x22 as default image format.
50      */
getInputFormat()51     default int getInputFormat() {
52         return retrieveOption(OPTION_INPUT_FORMAT);
53     }
54 
55     /**
56      * Retrieve the secondary input image format.
57      *
58      * <p>This is the format that is required for simultaneous capture. Currently only RAW + JPEG
59      * are supported and the input format must be set to RAW and secondary input format must be set
60      * to JPEG.
61      *
62      * <p>If the secondary input format is not set, {@link ImageFormat#UNKNOWN} will be returned.
63      */
getSecondaryInputFormat()64     default int getSecondaryInputFormat() {
65         return retrieveOption(OPTION_SECONDARY_INPUT_FORMAT, ImageFormat.UNKNOWN);
66     }
67 
68     /**
69      * Retrieve the required input {@link DynamicRange}.
70      *
71      * <p>This is the dynamic range that is required as input and it must be
72      * satisfied by the producer.
73      *
74      * <p>This method never throws. If the dynamic range is not set,
75      * {@link DynamicRange#UNSPECIFIED} will be returned.
76      */
getDynamicRange()77     default @NonNull DynamicRange getDynamicRange() {
78         return Preconditions.checkNotNull(retrieveOption(OPTION_INPUT_DYNAMIC_RANGE,
79                 DynamicRange.UNSPECIFIED));
80     }
81 
82     /**
83      * Returns whether a dynamic range was set on this config.
84      *
85      * <p>This method can be used to determine whether a dynamic range has been set to override
86      * the default {@link DynamicRange#UNSPECIFIED}.
87      */
hasDynamicRange()88     default boolean hasDynamicRange() {
89         return containsOption(OPTION_INPUT_DYNAMIC_RANGE);
90     }
91 
92     /**
93      * Builder for a {@link ImageInputConfig}.
94      *
95      * @param <B> The top level builder type for which this builder is composed with.
96      */
97     interface Builder<B> {
98         /**
99          * Sets the dynamic range required for images from this configuration.
100          *
101          * <p>Valid values depend on the specific configuration. The default behavior when not
102          * set is to automatically choose a dynamic range based on device capabilities and the
103          * dynamic range requested by other use cases, but use cases should override that
104          * behavior if needed.
105          *
106          * @param dynamicRange The dynamic range required for this configuration.
107          * @return The current Builder.
108          */
setDynamicRange(@onNull DynamicRange dynamicRange)109         @NonNull B setDynamicRange(@NonNull DynamicRange dynamicRange);
110     }
111 }
112