Application Note: Enabling Manual 3A Features 80 NU119 1
User Manual: Pdf
Open the PDF directly: View PDF 
.
Page Count: 16
Enabling Manual 3A Features
Application Note
80-NU119-1 A
November 19, 2014
Submit technical questions at:
https://support.cdmatech.com/
Confidential and Proprietary – Qualcomm Technologies, Inc.
NO PUBLIC DISCLOSURE PERMITTED: Please report postings of this document on public servers or websites
to: DocCtrlAgent@qualcomm.com.
Restricted Distribution: Not to be distributed to anyone who is not an employee of either Qualcomm or its
subsidiaries without the express approval of Qualcomm’s Configuration Management.
Not to be used, copied, reproduced, or modified in whole or in part, nor its contents revealed in any manner to others
without the express written permission of Qualcomm Technologies, Inc.
Qualcomm reserves the right to make changes to the product(s) or information contained herein without notice. No
liability is assumed for any damages arising directly or indirectly by their use or application. The information
provided in this document is provided on an “as is” basis.
This document contains confidential and proprietary information and must be shredded when discarded.
Qualcomm is a trademark of QUALCOMM Incorporated, registered in the United States and other countries. All
QUALCOMM Incorporated trademarks are used with permission. Other product and brand names may be
trademarks or registered trademarks of their respective owners.
This technical data may be subject to U.S. and international export, re-export, or transfer (“export”) laws. Diversion
contrary to U.S. and international law is strictly prohibited.
Qualcomm Technologies, Inc.
5775 Morehouse Drive
San Diego, CA 92121
U.S.A.
© 2014 Qualcomm Technologies, Inc.
All rights reserved.
Contents
1 Introduction ...................................................................................................... 5
1.1 Purpose.......................................................................................................................... 5
1.2 Conventions .................................................................................................................. 5
1.3 References ..................................................................................................................... 5
1.4 Technical assistance ...................................................................................................... 5
1.5 Acronyms ...................................................................................................................... 5
2 Manual 3A Features ......................................................................................... 6
2.1 Manual exposure control............................................................................................... 6
2.1.1 ISO priority ........................................................................................................ 7
2.1.2 Exposure time priority ....................................................................................... 8
2.1.3 User setting ...................................................................................................... 10
2.2 Manual white balance ................................................................................................. 10
2.2.1 Color temperature ............................................................................................ 11
2.2.2 RGB gains ........................................................................................................ 12
2.3 Manual focus ............................................................................................................... 13
2.3.1 Scale mode ....................................................................................................... 14
2.3.2 Diopter mode ................................................................................................... 14
2.4 Reference paths ........................................................................................................... 15
80-NU119-1 A 2 Confidential and Proprietary – Qualcomm Technologies, Inc.
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Contents
Tables
Table 1-1 Reference documents and standards ............................................................................................ 5
Table 2-1 Camera parameters ...................................................................................................................... 6
Table 2-2 ISO priority parameters ............................................................................................................... 7
Table 2-3 Exposure time priority parameters............................................................................................... 8
Table 2-4 Manual white balance parameters ............................................................................................. 10
Table 2-5 Color temperature camera parameters ....................................................................................... 11
Table 2-6 RGB camera parameters ............................................................................................................ 12
Table 2-7 Manual focus camera parameters .............................................................................................. 13
Table 2-8 Scale mode camera parameters .................................................................................................. 14
Table 2-9 Diopter mode camera parameters .............................................................................................. 14
Figures
Figure 2-1 Illustration of manual exposure feature .................................................................................... 16
80-NU119-1 A 3 Confidential and Proprietary – Qualcomm Technologies, Inc.
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Revision history
Revision Date Description
A Nov 2014 Initial release
.
80-NU119-1 A 4 Confidential and Proprietary – Qualcomm Technologies, Inc.
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
1 Introduction
1.1 Purpose
This document lists out the guidelines for application developers to enable manual 3A features.
1.2 Conventions
Function declarations, function names, type declarations, and code samples appear in a different
font, e.g., #include.
Code variables appear in angle brackets, e.g., <number>.
1.3 References
Reference documents are listed in Table 1-1. Reference documents that are no longer applicable
are deleted from this table; therefore, reference numbers may not be sequential.
Table 1-1 Reference documents and standards
Ref. Document
Qualcomm Technologies
Q1 Application Note: Software Glossary for Customers CL93-V3077-1
1.4 Technical assistance
For assistance or clarification on information in this document, submit a case to Qualcomm
Technologies, Inc. (QTI) at https://support.cdmatech.com/.
If you do not have access to the CDMATech Support website, register for access or send email to
support.cdmatech@qti.qualcomm.com.
1.5 Acronyms
For definitions of terms and abbreviations, see [Q1].
80-NU119-1 A 5 Confidential and Proprietary – Qualcomm Technologies, Inc.
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
2 Manual 3A Features
Manual 3A is supported in non-ZSL mode with no other configuration settings like AE
bracketing, HDR, Scene mode, brightness, flash, anti-banding and face priority, and Camcorder.
The manual white balance and focus settings are applied in both non-ZSL preview and snapshot,
however, the manual exposure settings take effect only in snapshot.
NOTE: These features are sensor dependent and would need changes in sensor driver code and exposure
capabilities. The support range for exposure time, ISO, and focus depends upon the sensor and
actuator capabilities.
The following are the Manual 3A features:
Manual exposure control
Manual white balance
Manual focus
2.1 Manual exposure control
The following modes are supported in manual exposure control feature:
ISO priority – User must provide ISO but exposure time is auto calculated by AEC.
Exposure time priority – User must provide exposure time but ISO is auto calculated by AEC
algorithm.
User-provided ISO and exposure time – This mode is fully manual. Both ISO and exposure
time directly taken from user input, but no auto calculation is involved.
NOTE: Settings are applied to snapshot only. Camera preview remains unchanged.
The following table explains the supported manual exposure modes queried from camera
parameters:
Table 2-1 Camera parameters
Purpose Camera parameter Value/Result(s)
To check for
supported
manual
exposure
modes
manual-exposure-modes Off, ISO-priority, exp-time-priority, user-setting – If any
of the modes is not supported, corresponding entry is
excluded in the query result. In such cases, it is
suggested that the corresponding entry is removed in
the application UI as well.
80-NU119-1 A 6 Confidential and Proprietary – Qualcomm Technologies, Inc.
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Manual 3A Features
2.1.1 ISO priority
In legacy/existing ISO feature, the user can set only discrete ISO values such as 200, 400, and
1600. However, in the new ISO-priority (or continuous ISO) mode, user is able to set any value
between minimum ISO until the maximum ISO supported by the sensor.
Table 2-2 ISO priority parameters
Purpose Parameter string Value
Minimum ISO min-iso Depends on sensor capability
Maximum ISO max-iso Depends on sensor capability
Set continuous ISO continuous-iso Any integer within the supported range
Get preview ISO cur-iso Retrieves the ISO to be applied for preview. The ISO is
used as a reference value for the user to set appropriate
ISO in snapshot.
Application settings
1. Set legacy ISO mode to manual.
2. Set continuous ISO to appropriate value.
3. Set Exposure time to 0 (auto exposure).
Sample code
Int minISO = mParameters.getInt(“min-iso”);
Int maxISO = mParameters.getInt(“max-iso”);
Int userinput;
if( userinput >= minISO && userinput <= maxISO)
{
mParameters.set(“iso”,“manual”);
mParameters.setInt(“continuous-iso”, userinput);
mParameters.set(“exposure-time”,”0”);
mCameraDevice.setParameters(mParameters);
}
To switch back to legacy ISO mode, the legacy ISO parameter must be set to any of the discrete
values or ISO_AUTO. In such a case, the continuous ISO, even if set, is ignored.
Sensor driver engineers to ensure that the capabilities for ISO are filled appropriately in the
sensor driver structures from exposure table.
80-NU119-1 A 7 Confidential and Proprietary – Qualcomm Technologies, Inc.
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Manual 3A Features
Reference driver path
/vendor/qcom/proprietary/mm-camera/mm-camera2/media
controller/modules/sensors/sensor_libs/imx135_lib.c
Sample code
static sensor_manual_exposure_info_t manual_exp_info = {
.min_exposure_time = 10587,/*in nano sec = 1line*/
.max_exposure_time = 693863262,/*in nano sec = FFFF lines*/
.min_iso = 100,
.max_iso = 800,
};
2.1.2 Exposure time priority
In this mode, the user can set any exposure time within the range supported by the sensor that is
used. ISO is set to Auto in this mode.
Table 2-3 Exposure time priority parameters
Purpose Parameter string Value
Minimum exposure time min-exposure-time Depends on sensor capability
Maximum exposure time max-exposure-time Depends on sensor capability
Set exposure time exposure-time Any float value within the supported range.
If exposure time is zero, Auto-exposure mode is
enabled.
Get preview exposure time cur-exposure-time Retrieves the exposure time applied for
preview. The exposure time is used as a
reference value for the user to set appropriate
exposure time in snapshot.
NOTE: All values are in milliseconds and are floating point numbers. If the user wants to set the
exposure time in other modes like for example, 1/5 sec, the application automatically converts it
into milliseconds when camera parameters are set.
80-NU119-1 A 8 Confidential and Proprietary – Qualcomm Technologies, Inc.
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Manual 3A Features
Application settings
1. Set appropriate exposure time in milliseconds.
2. Set ISO to Auto mode.
Sample code
final String minExpTime = mParameters.get(“min-exposure-time”);
final String maxExpTime = mParameters.get(“max-exposure-time”);
double userIinput; //in millisec
if (userIinput <= Double.parseDouble(maxExpTime) &&
userIinput >= Double.parseDouble(minExpTime)) {
mParameters.set(“exposure-time”, userIinput);
mParameters.set(“iso”,”auto”);
mCameraDevice.setParameters(mParameters);
}
Sensor driver engineers to make sure that the capabilities of Exposure time is filled appropriately
in the sensor driver structures as per sensor vendor recommendations. Some sensors also can
support long exposure times that must be programmed to the respective sensor drivers. For
simplicity and back ward compatibility a new variable, use_long_exposure in sensor_exp_info
structure is introduced. The following is the sample code.
Reference driver path
/vendor/qcom/proprietary/mm-camera/mm-camera2/media
controller/modules/sensors/sensor_libs/imx135_lib.c
Sample code
static sensor_manual_exposure_info_t manual_exp_info = {
.min_exposure_time = 10587,/*in nano sec = 1line*/
.max_exposure_time = 693863262,/*in nano sec = FFFF lines*/
.min_iso = 100,
.max_iso = 800,
};
static int32_t imx135_calculate_exposure(float real_gain,
uint32_t line_count,
sensor_exposure_info_t* exp_info) {
if (!exp_info) {
return -1;
}
if(exp_info->use_long_exposure == 1) {
exp_info->long_line_count = line_count;
}
else {
exp_info->line_count = line_count & 0xFFFF;
}
80-NU119-1 A 9 Confidential and Proprietary – Qualcomm Technologies, Inc.
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Manual 3A Features
2.1.3 User setting
In ISO priority mode, the ISO is manually set. However, the exposure time is auto-calculated. In
the Exposure time priority mode, the exposure time is manually set but the ISO is in Auto mode.
In the User setting mode, both the ISO and exposure must be set manually. The camera
parameters remain the same as in ISO priority and Exposure time priority modes.
Sample code
final String minExpTime = mParameters.get(“min-exposure-time”);
final String maxExpTime = mParameters.get(“max-exposure-time”);
Int minISO = mParameters.getInt(“min-iso”);
Int maxISO = mParameters.getInt(“max-iso”);
Int userISOinput;
double userExpTimeIinput; //in millisec
if (userExpTimeIinput <= Double.parseDouble(maxExpTime) &&
userExpTimeIinput >= Double.parseDouble(minExpTime) &&
userISOinput >= minISO && userISOinput <= maxISO) {
mParameters.set(“exposure-time”, userIinput);
mParameters.set(“iso”,“manual”);
mParameters.setInt(“continuous-iso”, userinput);
mCameraDevice.setParameters(mParameters);
}
2.2 Manual white balance
The following modes are supported in manual white balance feature:
Color temperature (CCT)
RBGB gains
These settings are applied to preview and snapshot.
Application settings
1. Set White balance mode to Manual mode.
2. Set manual white balance type to CCT or RBGB
3. Set appropriate value in CCT or RBGB.
To turn off manual white balance (WB), change White balance mode to Auto or any other mode.
Table 2-4 Manual white balance parameters
Purpose Parameter string Value/Result
To check for supported manual white
balance modes manual-wb-modes Off, color-temperature, rbgb-gains – The
manual white balance for bayer sensors is
by default supported. For YUV sensors,
there is no support and hence the result to
this query would be only “off”.
80-NU119-1 A 10 Confidential and Proprietary – Qualcomm Technologies, Inc.
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Manual 3A Features
Purpose Parameter string Value/Result
To set manual white balance type manual-wb-type 0 for CCT mode, 1 for RBGB gain mode
To set manual white balance value manual-wb-value User input in CCT or RBGB gain mode –
Valid input, input format, and supported
range for each mode is explained in the
next sections.
2.2.1 Color temperature
In the color temperature mode, the color temperature between minimum CCT and maximum CCT
can be set depending on the camera capabilities.
Table 2-5 Color temperature camera parameters
Purpose Camera parameter Value
Minimum CCT min-wb-cct 2000 (hardcoded in HAL)
Maximum CCT max-wb-cct 8000 (hardcoded in HAL)
Get current WB in CCT wb-manual-cct Get current white balance in CCT
Sample code
Int minCCT = mParameters.getInt(“min-wb-cct”);
Int maxCCT = mParameters.getInt(“max-wb-cct”);
Int userinput = 5000;
If (userInput <= maxCCT && userInput >= minCCT) {
mParameters.setWhiteBalance(“manual”);
mParameters.set("manual-wb-type", 0);
mParameters.set("manual-wb-value", userinput);
mCameradevice.setparameters(mParameters);
}
80-NU119-1 A 11 Confidential and Proprietary – Qualcomm Technologies, Inc.
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Manual 3A Features
2.2.2 RGB gains
In RGB gains mode, user can set R, G, B gains as a set in the range 1.0 to 4.0 (hardcoded for
now). Expected input format is “R_gain, G_gain, B_gain” as a string.
Table 2-6 RGB camera parameters
Purpose Camera parameter Value
Minimum gain min-wb-gain 1.0 (hardcoded in HAL)
Maximum gain max-wb-gain 4.0 (hardcoded in HAL)
Get current WB in RGB gain mode manual-wb-gains Get current RGB gains to be applied.
Result is in the format “R_gain, G_gain,
B_gain”, where each gain is a float value
in the range mentioned in previous
sections. For example, “2.5,3.0,1.0”
Sample code
String minGain = mParameters.get(“min-wb-gain”);
String maxGain = mParameters.get(“max-wb-gain”);
String userInput = “2.5,3.0,1.4”;
//parse user input and validate it with supported range
mParameters.setWhiteBalance(“manual”);
mParameters.set("manual-wb-type", 1);
mParameters.set("manual-wb-value", userinput);
mCameradevice.setparameters(mParameters);
NOTE: There is no one-to-one mapping between CCT and R, G, and B gains. Based on 2-D interpolation
of R, G, and B weights, the current CCT value is calculated. So, it is expected that inputting the
same displayed CCT value results in different gains and the final effect is different to that of the
current preview.
NOTE: Typically R and B gains are higher than G gain. Inputting equal gain values in manual R, G, and
B options results in green shade of preview/snapshot as there are two green channels in RGBG
Bayer grid. It is assumed that the user knows the Bayer grid pattern and inputs the gains
accordingly.
80-NU119-1 A 12 Confidential and Proprietary – Qualcomm Technologies, Inc.
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Manual 3A Features
2.3 Manual focus
The following modes are supported in the manual focus feature:
Scale mode (0-100 scale), zero meaning near distance.
Diopter-based – The diopter value in 1/meter (reciprocal of focal length) as a float value is
provided.
Application settings
1. Set Focus mode to manual.
2. Set focus type to scale or diopter.
3. Set focus position.
To turn off manual focus, change the Focus mode to other modes such as Auto, CAF, etc.
Table 2-7 Manual focus camera parameters
Purpose Camera parameter Value/Result
To check for supported
manual focus modes manual-focus-modes Off, scale-mode, diopter-mode
To set manual focus type manual-focus-pos-type 2 for Scale mode, 3 for Diopter mode
To set manual focus position manual-focus-position User to input in Scale mode or Diopter
mode.
The Scale mode range is 0-100. It is
queried from camera parameters as well.
Input must be an integer.
Range for Diopter mode depends on
sensor and are queried from camera
parameters. Input is a float value.
80-NU119-1 A 13 Confidential and Proprietary – Qualcomm Technologies, Inc.
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Manual 3A Features
2.3.1 Scale mode
Table 2-8 Scale mode camera parameters
Value Camera parameter Value
Minimum scale min-focus-pos-ratio 0 (hardcoded in HAL)
Maximum scale max-focus-pos-ratio 100 (hardcoded in HAL)
Get current focus position in
scale mode cur-focus-scale Current focus position in the supported
range. This can be used as a reference
value for the user to know how much more
lens needs to be moved.
Sample code
int minFocus = mParameters.getInt("min-focus-pos-ratio");
int maxFocus = mParameters.getInt("max-focus-pos-ratio");
mParameters.setFocusMode("manual");
mParameters.set("manual-focus-pos-type", 2);
mParameters.set("manual-focus-position", 70);
mCameraDevice.setParameters(mParameters);
2.3.2 Diopter mode
Table 2-9 Diopter mode camera parameters
Purpose Camera parameter Value
Minimum diopter min-focus-pos-diopter 0 (hardcoded in HAL)
Maximum diopter max-focus-pos-diopter Sensor dependent
Get current focus position in
Diopter mode cur-focus-diopter Current focus position in the supported
range. This can be used as a reference
value for the user to know how much more
lens needs to be moved.
Sample code
String minFocusStr = mParameters.get("min-focus-pos-diopter");
String maxFocusStr = mParameters.get("max-focus-pos-diopter");
final float minFocusPos = Float.parseFloat(minFocusStr);
final float maxFocusPos = Float.parseFloat(maxFocusStr);
mParameters.setFocusMode("manual");
mParameters.set("manual-focus-pos-type", 3);
mParameters.set("manual-focus-position", 4.5);
mCameraDevice.setParameters(mParameters);
80-NU119-1 A 14 Confidential and Proprietary – Qualcomm Technologies, Inc.
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Manual 3A Features
Sensor driver engineers should fill the focus near end capability appropriately as per the
maximum capability of the actuator inside the sensor driver structure. The fare end is considered
to be INFINITY by default.
Reference driver path
/vendor/qcom/proprietary/mm-camera/mm-camera2/media
controller/modules/sensors/sensor_libs/imx135_lib.c
Sample code
static sensor_lens_info_t default_lens_info = {
.focal_length = 4.6,
.pix_size = 1.4,
.f_number = 2.65,
.total_f_dist = 1.97,
.hor_view_angle = 54.8,
.ver_view_angle = 42.5,
.near_end_distance = 10,/*in cm*/
};
2.4 Reference paths
Sample implementation of Manual 3A in application layer can be referenced at the following
paths (based on the Android version):
Lollipop – \packages\apps\SnapdragonCamera\src\com\android\camera\PhotoModule.java
Kitkat – \packages\apps\Camera2\src\com\android\camera\PhotoModule.java
Core functions which do necessary settings (common in both Android versions):
UpdateManualExposureSettings()
UpdateManualWBSettings()
UpdateManualFocusSettings()
NOTE: In the reference implementation, all Manual 3A settings are turned off (get reset to default) when
camera application is closed.
80-NU119-1 A 15 Confidential and Proprietary – Qualcomm Technologies, Inc.
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Manual 3A Features
Test example for manual exposure
Figure 2-1 gives an illustration of manual exposure feature tested with different options under
same lighting conditions.
This set of snaps were taken using a tripod in dark lighting conditions with a sensor that supports
long exposure times (up to 86 sec with QTI test sensor).
Figure 2-1 Illustration of manual exposure feature
80-NU119-1 A 16 Confidential and Proprietary – Qualcomm Technologies, Inc.
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
