Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 0273e10c authored by Eino-Ville Talvala's avatar Eino-Ville Talvala
Browse files

Camera: Improve reference docs for lensShadingApplied 

Make it clear that there may be still be more lens shading to be
applied to match RAW and processed frames.

Also fix some minor formatting in new flash strength docs.

Flag: Doc only change
Test: Builds
Change-Id: I2fa4641416465b807a23bb5341c81627973204c9
parent ae526745

core/java/android/hardware/camera2/CameraCharacteristics.java

+16 −10
Original line number Diff line number Diff line
@@ -1472,9 +1472,9 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 
            new Key<Integer>("android.flash.info.strengthDefaultLevel", int.class);



    /**

     * <p>Maximum flash brightness level for manual flash control in SINGLE mode.</p>

     * <p>Maximum flash brightness level for manual flash control in <code>SINGLE</code> mode.</p>

     * <p>Maximum flash brightness level in camera capture mode and

     * {@link CaptureRequest#FLASH_MODE android.flash.mode} set to SINGLE.

     * {@link CaptureRequest#FLASH_MODE android.flash.mode} set to <code>SINGLE</code>.

     * Value will be &gt; 1 if the manual flash strength control feature is supported,

     * otherwise the value will be equal to 1.

     * Note that this level is just a number of supported levels (the granularity of control).
@@ -1490,7 +1490,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 
            new Key<Integer>("android.flash.singleStrengthMaxLevel", int.class);



    /**

     * <p>Default flash brightness level for manual flash control in SINGLE mode.</p>

     * <p>Default flash brightness level for manual flash control in <code>SINGLE</code> mode.</p>

     * <p>If flash unit is available this will be greater than or equal to 1 and less

     * or equal to {@link CameraCharacteristics#FLASH_SINGLE_STRENGTH_MAX_LEVEL android.flash.singleStrengthMaxLevel}.

     * Note for devices that do not support the manual flash strength control
@@ -1506,9 +1506,9 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 
            new Key<Integer>("android.flash.singleStrengthDefaultLevel", int.class);



    /**

     * <p>Maximum flash brightness level for manual flash control in TORCH mode</p>

     * <p>Maximum flash brightness level for manual flash control in <code>TORCH</code> mode</p>

     * <p>Maximum flash brightness level in camera capture mode and

     * {@link CaptureRequest#FLASH_MODE android.flash.mode} set to TORCH.

     * {@link CaptureRequest#FLASH_MODE android.flash.mode} set to <code>TORCH</code>.

     * Value will be &gt; 1 if the manual flash strength control feature is supported,

     * otherwise the value will be equal to 1.</p>

     * <p>Note that this level is just a number of supported levels(the granularity of control).
@@ -1530,7 +1530,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 
            new Key<Integer>("android.flash.torchStrengthMaxLevel", int.class);



    /**

     * <p>Default flash brightness level for manual flash control in TORCH mode</p>

     * <p>Default flash brightness level for manual flash control in <code>TORCH</code> mode</p>

     * <p>If flash unit is available this will be greater than or equal to 1 and less

     * or equal to {@link CameraCharacteristics#FLASH_TORCH_STRENGTH_MAX_LEVEL android.flash.torchStrengthMaxLevel}.

     * Note for the devices that do not support the manual flash strength control feature,
@@ -4152,10 +4152,16 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 
    /**

     * <p>Whether the RAW images output from this camera device are subject to

     * lens shading correction.</p>

     * <p>If TRUE, all images produced by the camera device in the RAW image formats will

     * have lens shading correction already applied to it. If FALSE, the images will

     * not be adjusted for lens shading correction.

     * See {@link CameraCharacteristics#REQUEST_MAX_NUM_OUTPUT_RAW android.request.maxNumOutputRaw} for a list of RAW image formats.</p>

     * <p>If <code>true</code>, all images produced by the camera device in the <code>RAW</code> image formats will have

     * at least some lens shading correction already applied to it. If <code>false</code>, the images will

     * not be adjusted for lens shading correction.  See {@link CameraCharacteristics#REQUEST_MAX_NUM_OUTPUT_RAW android.request.maxNumOutputRaw} for a

     * list of RAW image formats.</p>

     * <p>When <code>true</code>, the <code>lensShadingCorrectionMap</code> key may still have values greater than 1.0,

     * and those will need to be applied to any captured RAW frames for them to match the shading

     * correction of processed buffers such as <code>YUV</code> or <code>JPEG</code> images. This may occur, for

     * example, when some basic fixed lens shading correction is applied by hardware to RAW data,

     * and additional correction is done dynamically in the camera processing pipeline after

     * demosaicing.</p>

     * <p>This key will be <code>null</code> for all devices do not report this information.

     * Devices with RAW capability will always report this information in this key.</p>

     * <p><b>Optional</b> - The value for this key may be {@code null} on some devices.</p>

core/java/android/hardware/camera2/CaptureRequest.java

+6 −6
Original line number Diff line number Diff line
@@ -2683,27 +2683,27 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> 
    /**

     * <p>Flash strength level to be used when manual flash control is active.</p>

     * <p>Flash strength level to use in capture mode i.e. when the applications control

     * flash with either SINGLE or TORCH mode.</p>

     * flash with either <code>SINGLE</code> or <code>TORCH</code> mode.</p>

     * <p>Use {@link CameraCharacteristics#FLASH_SINGLE_STRENGTH_MAX_LEVEL android.flash.singleStrengthMaxLevel} and

     * {@link CameraCharacteristics#FLASH_TORCH_STRENGTH_MAX_LEVEL android.flash.torchStrengthMaxLevel} to check whether the device supports

     * flash strength control or not.

     * If the values of android.flash.info.singleStrengthMaxLevel and

     * If the values of {@link CameraCharacteristics#FLASH_SINGLE_STRENGTH_MAX_LEVEL android.flash.singleStrengthMaxLevel} and

     * {@link CameraCharacteristics#FLASH_TORCH_STRENGTH_MAX_LEVEL android.flash.torchStrengthMaxLevel} are greater than 1,

     * then the device supports manual flash strength control.</p>

     * <p>If the {@link CaptureRequest#FLASH_MODE android.flash.mode} <code>==</code> TORCH the value must be &gt;= 1

     * <p>If the {@link CaptureRequest#FLASH_MODE android.flash.mode} <code>==</code> <code>TORCH</code> the value must be &gt;= 1

     * and &lt;= {@link CameraCharacteristics#FLASH_TORCH_STRENGTH_MAX_LEVEL android.flash.torchStrengthMaxLevel}.

     * If the application doesn't set the key and

     * {@link CameraCharacteristics#FLASH_TORCH_STRENGTH_MAX_LEVEL android.flash.torchStrengthMaxLevel} &gt; 1,

     * then the flash will be fired at the default level set by HAL in

     * {@link CameraCharacteristics#FLASH_TORCH_STRENGTH_DEFAULT_LEVEL android.flash.torchStrengthDefaultLevel}.

     * If the {@link CaptureRequest#FLASH_MODE android.flash.mode} <code>==</code> SINGLE, then the value must be &gt;= 1

     * If the {@link CaptureRequest#FLASH_MODE android.flash.mode} <code>==</code> <code>SINGLE</code>, then the value must be &gt;= 1

     * and &lt;= {@link CameraCharacteristics#FLASH_SINGLE_STRENGTH_MAX_LEVEL android.flash.singleStrengthMaxLevel}.

     * If the application does not set this key and

     * {@link CameraCharacteristics#FLASH_SINGLE_STRENGTH_MAX_LEVEL android.flash.singleStrengthMaxLevel} &gt; 1,

     * then the flash will be fired at the default level set by HAL

     * in {@link CameraCharacteristics#FLASH_SINGLE_STRENGTH_DEFAULT_LEVEL android.flash.singleStrengthDefaultLevel}.

     * If {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is set to any of ON_AUTO_FLASH, ON_ALWAYS_FLASH,

     * ON_AUTO_FLASH_REDEYE, ON_EXTERNAL_FLASH values, then the strengthLevel will be ignored.</p>

     * If {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is set to any of <code>ON_AUTO_FLASH</code>, <code>ON_ALWAYS_FLASH</code>,

     * <code>ON_AUTO_FLASH_REDEYE</code>, <code>ON_EXTERNAL_FLASH</code> values, then the strengthLevel will be ignored.</p>

     * <p><b>Range of valid values:</b><br>

     * <code>[1-{@link CameraCharacteristics#FLASH_TORCH_STRENGTH_MAX_LEVEL android.flash.torchStrengthMaxLevel}]</code> when the {@link CaptureRequest#FLASH_MODE android.flash.mode} is

     * set to TORCH;

core/java/android/hardware/camera2/CaptureResult.java

+9 −6
Original line number Diff line number Diff line
@@ -2976,27 +2976,27 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 
    /**

     * <p>Flash strength level to be used when manual flash control is active.</p>

     * <p>Flash strength level to use in capture mode i.e. when the applications control

     * flash with either SINGLE or TORCH mode.</p>

     * flash with either <code>SINGLE</code> or <code>TORCH</code> mode.</p>

     * <p>Use {@link CameraCharacteristics#FLASH_SINGLE_STRENGTH_MAX_LEVEL android.flash.singleStrengthMaxLevel} and

     * {@link CameraCharacteristics#FLASH_TORCH_STRENGTH_MAX_LEVEL android.flash.torchStrengthMaxLevel} to check whether the device supports

     * flash strength control or not.

     * If the values of android.flash.info.singleStrengthMaxLevel and

     * If the values of {@link CameraCharacteristics#FLASH_SINGLE_STRENGTH_MAX_LEVEL android.flash.singleStrengthMaxLevel} and

     * {@link CameraCharacteristics#FLASH_TORCH_STRENGTH_MAX_LEVEL android.flash.torchStrengthMaxLevel} are greater than 1,

     * then the device supports manual flash strength control.</p>

     * <p>If the {@link CaptureRequest#FLASH_MODE android.flash.mode} <code>==</code> TORCH the value must be &gt;= 1

     * <p>If the {@link CaptureRequest#FLASH_MODE android.flash.mode} <code>==</code> <code>TORCH</code> the value must be &gt;= 1

     * and &lt;= {@link CameraCharacteristics#FLASH_TORCH_STRENGTH_MAX_LEVEL android.flash.torchStrengthMaxLevel}.

     * If the application doesn't set the key and

     * {@link CameraCharacteristics#FLASH_TORCH_STRENGTH_MAX_LEVEL android.flash.torchStrengthMaxLevel} &gt; 1,

     * then the flash will be fired at the default level set by HAL in

     * {@link CameraCharacteristics#FLASH_TORCH_STRENGTH_DEFAULT_LEVEL android.flash.torchStrengthDefaultLevel}.

     * If the {@link CaptureRequest#FLASH_MODE android.flash.mode} <code>==</code> SINGLE, then the value must be &gt;= 1

     * If the {@link CaptureRequest#FLASH_MODE android.flash.mode} <code>==</code> <code>SINGLE</code>, then the value must be &gt;= 1

     * and &lt;= {@link CameraCharacteristics#FLASH_SINGLE_STRENGTH_MAX_LEVEL android.flash.singleStrengthMaxLevel}.

     * If the application does not set this key and

     * {@link CameraCharacteristics#FLASH_SINGLE_STRENGTH_MAX_LEVEL android.flash.singleStrengthMaxLevel} &gt; 1,

     * then the flash will be fired at the default level set by HAL

     * in {@link CameraCharacteristics#FLASH_SINGLE_STRENGTH_DEFAULT_LEVEL android.flash.singleStrengthDefaultLevel}.

     * If {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is set to any of ON_AUTO_FLASH, ON_ALWAYS_FLASH,

     * ON_AUTO_FLASH_REDEYE, ON_EXTERNAL_FLASH values, then the strengthLevel will be ignored.</p>

     * If {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is set to any of <code>ON_AUTO_FLASH</code>, <code>ON_ALWAYS_FLASH</code>,

     * <code>ON_AUTO_FLASH_REDEYE</code>, <code>ON_EXTERNAL_FLASH</code> values, then the strengthLevel will be ignored.</p>

     * <p><b>Range of valid values:</b><br>

     * <code>[1-{@link CameraCharacteristics#FLASH_TORCH_STRENGTH_MAX_LEVEL android.flash.torchStrengthMaxLevel}]</code> when the {@link CaptureRequest#FLASH_MODE android.flash.mode} is

     * set to TORCH;
@@ -4846,6 +4846,9 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 
     * correction map that needs to be applied to get shading

     * corrected images that match the camera device's output for

     * non-RAW formats.</p>

     * <p>Therefore, whatever the value of lensShadingApplied is, the lens

     * shading map should always be applied to RAW images if the goal is to

     * match the shading appearance of processed (non-RAW) images.</p>

     * <p>For a complete shading correction map, the least shaded

     * section of the image will have a gain factor of 1; all

     * other sections will have gains above 1.</p>