Starting March 27, 2025, we recommend using android-latest-release instead of aosp-main to build and contribute to AOSP. For more information, see Changes to AOSP.

Program camera control parameters

In the previous Extended View System (EVS) 1.0 release, camera devices were considered read-only devices and, therefore, no method existed that would enable the app to change camera control parameters such as zoom or brightness.

As this could constrain the capability of EVS apps, the new EVS 1.1 introduces new methods and enables the app to program several camera control parameters, all of which are defined in enum CameraParam:

/**
*EVSCameraParameter
*/
enumCameraParam:uint32_t{
/**
*Thebrightnessofimageframes
*/
BRIGHTNESS,
/**
*Thecontrastofimageframes
*/
CONTRAST,
/**
*Automaticgain/exposurecontrol
*/
AUTOGAIN,
/**
*Gaincontrol
*/
GAIN,
/**
*AutomaticWhitebalance
*/
AUTO_WHITE_BALANCE,
/**
*ManualwhitebalancesettingasacolortemperatureinKelvin.
*/
WHITE_BALANCE_TEMPERATURE,
/**
*Imagesharpnessadjustment
*/
SHARPNESS,
/**
*AutoExposureControlmodes;auto,manual,shutterpriority,or
*aperturepriority.
*/
AUTO_EXPOSURE,
/**
*Manualexposuretimeofthecamera
*/
ABSOLUTE_EXPOSURE,
/**
*Setthefocalpointofthecameratothespecifiedposition.This
*parametermaynotbeeffectivewhenautofocusisenabled.
*/
ABSOLUTE_FOCUS,
/**
*Enablescontinuousautomaticfocusadjustments.
*/
AUTO_FOCUS,
/**
*Specifytheobjectivelensfocallengthasanabsolutevalue.
*/
ABSOLUTE_ZOOM,
};

Methods are defined as:

/**
*Requeststobeamasterclient.
*
*Whenmultipleclientssubscribetoasinglecamerahardwareandoneof
*themadjustsacameraparametersuchasthecontrast,itmaydisturb
*otherclients' operations. Therefore, the client must call this method
*tobeamasterclient.Whenitbecomesamaster,itcan
*changecameraparametersuntileitheritdiesorexplicitlygivesupthe
*role.
*
*@returnresultEvsResult::OKifamasterroleisgranted.
*EvsResult::OWNERSHIP_LOSTifthereisalreadya
*masterclient.
*/
setMaster()generates(EvsResultresult);
/**
*Setstobeamasterclientforcibly.
*
*Theclient,whichownsthedisplay,hasahighpriorityandcantakeover
*amasterrolefromotherclientswithoutthedisplay.
*
*@paramdisplayIEvsDisplayhandle.Ifthisisvalid,thecallingclient
*isconsideredasthehighpriorityclientandtherefore
*itwouldtakeoveramasterrole.
*
*@returnresultEvsResult::OKifamasterroleisgranted.
*EvsResult::OWNERSHIP_LOSTifthereisalreadya
*masterclientwiththedisplay.
*/
forceMaster(IEvsDisplaydisplay)generates(EvsResultresult);
/**
*Retiresfromamasterclientrole.
*
*@returnresultEvsResult::OKifthiscallissuccessful.
*EvsResult::INVALID_ARGifthecallerclientisnota
*masterclient.
*/
unsetMaster()generates(EvsResultresult);
/**
*Retrievesalistofparametersthiscamerasupports.
*
*@returnparamsAlistofCameraParamthatthiscamerasupports.
*/
getParameterList()generates(vec<CameraParam>params);
/**
*Requestsavalidvaluerangeofacameraparameter
*
*@paramidTheidentifierofcameraparameter,CameraParamenum.
*
*@returnminThelowerboundofthevalidparametervaluerange.
*@returnmaxTheupperboundofthevalidparametervaluerange.
*@returnstepTheresolutionofvaluesinvalidrange.
*/
getIntParameterRange(CameraParamid)
generates(int32_tmin,int32_tmax,int32_tstep);
/**
*Requeststosetacameraparameter.
*
*@paramidTheidentifierofcameraparameter,
*CameraParamenum.
*valueAdesiredparametervalue.
*@returnresultEvsResult::OKifitsucceedstosetaparameter.
*EvsResult::INVALID_ARGifeitherarequested
*parameterisnotsupportedoragivenvalueisout
*ofbounds.
*effectiveValueAprogrammedparametervalue.Thismaydiffer
*fromwhattheclientgivesif,forexample,the
*driverdoesnotsupportatargetparameter.
*/
setIntParameter(CameraParamid,int32_tvalue)
generates(EvsResultresult,int32_teffectiveValue);
/**
*Retrievesavalueofgivencameraparameter.
*
*@paramidTheidentifierofcameraparameter,CameraParamenum.
*@returnresultEvsResult::OKifitsucceedstoreadaparameter.
*EvsResult::INVALID_ARGifeitherarequestedparameteris
*notsupported.
*valueAvalueofrequestedcameraparameter.
*/
getIntParameter(CameraParamid)generates(EvsResultresult,int32_tvalue);

getParameterList() returns a list of parameters (CameraParam enum) a client can read and write (if the client is a master), and getIntParameterRange() relays the valid value range and resolution. When a master client changes a camera parameter, all other clients on the same camera hardware are notified by getting a PARAMETER_CHANGED event with a parameter ID and new value.

Note: The sensor driver may handle invalid parameter values differently. It may simply return an error code or clip the value in the valid range and apply. Therefore, the setIntParameter() method returns an effective value and the client can use this value to confirm how the request was handled.

Request arbitration between multiple camera clients

Because the previous EVS design allowed multiple apps to simultaneously subscribe to a single camera hardware, it is possible that one app can disturb the operations of other apps by changing a camera parameter. Also, multiple clients may want to adjust the same parameter differently and thereby cause unexpected behaviors in running camera services.

To avoid such problems, the EVS manager allows that only master client to program a camera parameter. Before trying to adjust any camera parameter, the client MUST become a master client by calling the setMaster() method. If this fails, then it means there is already an active master client on that camera hardware. Until the current master client dies, or explicitly gives up a master role through unsetMaster(), no other client is permitted to change a camera parameter. When a master client returns its privilege, all other apps are notified by a MASTER_RELEASED event.

Clients with high priority

The EVS manager handles the client that owns the display with the high priority and allows it to steal a master role from a current master. Because EVS display ownership is based on recency, the new client can even take over from the current client with the display.

High priority clients must call IEvsCamera::forceMaster(sp<IEvsDisplay>& display) to attain a master role. The EVS manager examines the state of a given display handle and, if (and only if) its state is valid and neither DisplayState::NOT_OPEN nor DisplayState::DEAD replaces a master. The client, which just loses the master role, is notified by a MASTER_RELEASED event and MUST handle this properly.

Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.

Last updated 2024年09月03日 UTC.