FileDocCategorySizeDatePackage
AutoFocusStateMachine.javaAPI DocAndroid 5.1 API15510Thu Mar 12 22:22:48 GMT 2015com.android.ex.camera2.pos

AutoFocusStateMachine

public class AutoFocusStateMachine extends Object
Manage the auto focus state machine for CameraDevice.

Requests are created only when the AF needs to be manipulated from the user, but automatic camera-caused AF state changes are broadcasted from any new result.

Fields Summary
private static final String
TAG
private static final boolean
DEBUG_LOGGING
private static final boolean
VERBOSE_LOGGING
private static final int
AF_UNINITIALIZED
private final AutoFocusStateListener
mListener
private int
mLastAfState
private int
mLastAfMode
private int
mCurrentAfMode
private int
mCurrentAfTrigger
private int
mCurrentAfCookie
private String
mCurrentAfTrace
private int
mLastAfCookie
Constructors Summary
public AutoFocusStateMachine(AutoFocusStateListener listener)


       
        if (listener == null) {
            throw new IllegalArgumentException("listener should not be null");
        }
        mListener = listener;
Methods Summary
private synchronized voidbeginTraceAsync(java.lang.String sectionName)

        if (mCurrentAfCookie != AF_UNINITIALIZED) {
            // Terminate any currently active async sections before beginning another section
            SysTrace.endSectionAsync(mCurrentAfTrace, mCurrentAfCookie);
        }

        mLastAfCookie++;
        mCurrentAfCookie = mLastAfCookie;
        mCurrentAfTrace = sectionName;

        SysTrace.beginSectionAsync(sectionName, mCurrentAfCookie);
private synchronized voidendTraceAsync()

        if (mCurrentAfCookie == AF_UNINITIALIZED) {
            Log.w(TAG, "endTraceAsync - no current trace active");
            return;
        }

        SysTrace.endSectionAsync(mCurrentAfTrace, mCurrentAfCookie);
        mCurrentAfCookie = AF_UNINITIALIZED;
public synchronized voidlockAutoFocus(CaptureRequest.Builder repeatingBuilder, CaptureRequest.Builder requestBuilder)
Lock the lens from moving. Typically used before taking a picture.

After calling this function, submit the new requestBuilder as a separate capture. Do not submit it as a repeating request or the AF lock will be repeated every time.

Create a new repeating request from repeatingBuilder and set that as the updated repeating request.

If the lock succeeds, {@link AutoFocusStateListener#onAutoFocusSuccess} with {@code locked == true} will be invoked. If the lock fails, {@link AutoFocusStateListener#onAutoFocusFail} with {@code scanning == false} will be invoked.

param
repeatingBuilder Builder for a repeating request.
param
requestBuilder Builder for a non-repeating request.


        if (VERBOSE_LOGGING) Log.v(TAG, "lockAutoFocus");

        if (mCurrentAfMode == AF_UNINITIALIZED) {
            throw new IllegalStateException("AF mode was not enabled");
        }

        beginTraceAsync("AFSM_lockAutoFocus");

        mCurrentAfTrigger = CaptureRequest.CONTROL_AF_TRIGGER_START;

        repeatingBuilder.set(CaptureRequest.CONTROL_AF_MODE, mCurrentAfMode);
        requestBuilder.set(CaptureRequest.CONTROL_AF_MODE, mCurrentAfMode);

        repeatingBuilder.set(CaptureRequest.CONTROL_AF_TRIGGER,
                CaptureRequest.CONTROL_AF_TRIGGER_IDLE);
        requestBuilder.set(CaptureRequest.CONTROL_AF_TRIGGER,
                CaptureRequest.CONTROL_AF_TRIGGER_START);
public synchronized voidonCaptureCompleted(android.hardware.camera2.CaptureResult result)
Invoke every time we get a new CaptureResult via {@link CameraDevice.CaptureCallback#onCaptureCompleted}.

This function is responsible for dispatching updates via the {@link AutoFocusStateListener} so without calling this on a regular basis, no AF changes will be observed.

param
result CaptureResult


        /**
         * Work-around for b/11269834
         * Although these should never-ever happen, harden for ship
         */
        if (result == null) {
            Log.w(TAG, "onCaptureCompleted - missing result, skipping AF update");
            return;
        }

        Key<Integer> keyAfState = CaptureResult.CONTROL_AF_STATE;
        if (keyAfState == null) {
            Log.e(TAG, "onCaptureCompleted - missing android.control.afState key, " +
                    "skipping AF update");
            return;
        }

        Key<Integer> keyAfMode = CaptureResult.CONTROL_AF_MODE;
        if (keyAfMode == null) {
            Log.e(TAG, "onCaptureCompleted - missing android.control.afMode key, " +
                    "skipping AF update");
            return;
        }

        Integer afState = result.get(CaptureResult.CONTROL_AF_STATE);
        Integer afMode = result.get(CaptureResult.CONTROL_AF_MODE);

        /**
         * Work-around for b/11238865
         * This is a HAL bug as these fields should be there always.
         */
        if (afState == null) {
            Log.w(TAG, "onCaptureCompleted - missing android.control.afState !");
            return;
        } else if (afMode == null) {
            Log.w(TAG, "onCaptureCompleted - missing android.control.afMode !");
            return;
        }

        if (DEBUG_LOGGING) Log.d(TAG, "onCaptureCompleted - new AF mode = " + afMode +
                " new AF state = " + afState);

        if (mLastAfState == afState && afMode == mLastAfMode) {
            // Same AF state as last time, nothing else needs to be done.
            return;
        }

        if (VERBOSE_LOGGING) Log.v(TAG, "onCaptureCompleted - new AF mode = " + afMode +
                " new AF state = " + afState);

        mLastAfState = afState;
        mLastAfMode = afMode;

        switch (afState) {
            case CaptureResult.CONTROL_AF_STATE_FOCUSED_LOCKED:
                mListener.onAutoFocusSuccess(result, /*locked*/true);
                endTraceAsync();
                break;
            case CaptureResult.CONTROL_AF_STATE_NOT_FOCUSED_LOCKED:
                mListener.onAutoFocusFail(result, /*locked*/true);
                endTraceAsync();
                break;
            case CaptureResult.CONTROL_AF_STATE_PASSIVE_FOCUSED:
                mListener.onAutoFocusSuccess(result, /*locked*/false);
                break;
            case CaptureResult.CONTROL_AF_STATE_PASSIVE_UNFOCUSED:
                mListener.onAutoFocusFail(result, /*locked*/false);
                break;
            case CaptureResult.CONTROL_AF_STATE_ACTIVE_SCAN:
                mListener.onAutoFocusScan(result);
                break;
            case CaptureResult.CONTROL_AF_STATE_PASSIVE_SCAN:
                mListener.onAutoFocusScan(result);
                break;
            case CaptureResult.CONTROL_AF_STATE_INACTIVE:
                mListener.onAutoFocusInactive(result);
                break;
        }
public synchronized voidresetState()
Reset the current AF state.

When dropping capture results (by not invoking {@link #onCaptureCompleted} when a new {@link CaptureResult} is available), call this function to reset the state. Otherwise the next time a new state is observed this class may incorrectly consider it as the same state as before, and not issue any callbacks by {@link AutoFocusStateListener}. 

        if (VERBOSE_LOGGING) Log.v(TAG, "resetState - last state was " + mLastAfState);

        mLastAfState = AF_UNINITIALIZED;
public synchronized voidsetActiveAutoFocus(CaptureRequest.Builder repeatingBuilder, CaptureRequest.Builder requestBuilder)
Enable active auto focus, immediately triggering a converging scan.

This is typically only used when locking the passive AF has failed.

Once active AF scanning starts, {@link AutoFocusStateListener#onAutoFocusScan} will be invoked.

If the active scan succeeds, {@link AutoFocusStateListener#onAutoFocusSuccess} with {@code locked == true} will be invoked. If the active scan fails, {@link AutoFocusStateListener#onAutoFocusFail} with {@code scanning == false} will be invoked.

After calling this function, submit the new requestBuilder as a separate capture. Do not submit it as a repeating request or the AF trigger will be repeated every time.

Create a new repeating request from repeatingBuilder and set that as the updated repeating request.

param
repeatingBuilder Builder for a repeating request.
param
requestBuilder Builder for a non-repeating request.
param
repeatingBuilder Builder for a repeating request.

        if (VERBOSE_LOGGING) Log.v(TAG, "setActiveAutoFocus");

        beginTraceAsync("AFSM_setActiveAutoFocus");

        mCurrentAfMode = CaptureRequest.CONTROL_AF_MODE_AUTO;

        repeatingBuilder.set(CaptureRequest.CONTROL_AF_MODE, mCurrentAfMode);
        requestBuilder.set(CaptureRequest.CONTROL_AF_MODE, mCurrentAfMode);

        repeatingBuilder.set(CaptureRequest.CONTROL_AF_TRIGGER,
                CaptureRequest.CONTROL_AF_TRIGGER_IDLE);
        requestBuilder.set(CaptureRequest.CONTROL_AF_TRIGGER,
                CaptureRequest.CONTROL_AF_TRIGGER_START);
public synchronized voidsetPassiveAutoFocus(boolean picture, CaptureRequest.Builder repeatingBuilder)
Enable passive autofocus, immediately triggering a non-converging scan.

While passive autofocus is enabled, use {@link #lockAutoFocus} to lock the lens before taking a picture. Once a picture is taken, use {@link #unlockAutoFocus} to let the lens go back into passive scanning.

Once passive AF scanning starts, {@link AutoFocusStateListener#onAutoFocusScan} will be invoked.

param
repeatingBuilder Builder for a repeating request.
param
picture True for still capture AF, false for video AF.

        if (VERBOSE_LOGGING) Log.v(TAG, "setPassiveAutoFocus - picture " + picture);

        if (picture) {
            mCurrentAfMode = CaptureResult.CONTROL_AF_MODE_CONTINUOUS_PICTURE;
        } else {
            mCurrentAfMode = CaptureResult.CONTROL_AF_MODE_CONTINUOUS_VIDEO;
        }

        repeatingBuilder.set(CaptureRequest.CONTROL_AF_MODE, mCurrentAfMode);
public synchronized voidunlockAutoFocus(CaptureRequest.Builder repeatingBuilder, CaptureRequest.Builder requestBuilder)
Unlock the lens, allowing it to move again. Typically used after taking a picture.

After calling this function, submit the new requestBuilder as a separate capture. Do not submit it as a repeating request or the AF lock will be repeated every time.

Create a new repeating request from repeatingBuilder and set that as the updated repeating request.

Once the unlock takes effect, {@link AutoFocusStateListener#onAutoFocusInactive} is invoked, and after that the effects depend on which mode you were in:

  • Passive - Scanning restarts with {@link AutoFocusStateListener#onAutoFocusScan}
  • Active - The lens goes back to a default position (no callbacks)

param
repeatingBuilder Builder for a repeating request.
param
requestBuilder Builder for a non-repeating request.


        if (VERBOSE_LOGGING) Log.v(TAG, "unlockAutoFocus");

        if (mCurrentAfMode == AF_UNINITIALIZED) {
            throw new IllegalStateException("AF mode was not enabled");
        }

        mCurrentAfTrigger = CaptureRequest.CONTROL_AF_TRIGGER_CANCEL;

        repeatingBuilder.set(CaptureRequest.CONTROL_AF_MODE, mCurrentAfMode);
        requestBuilder.set(CaptureRequest.CONTROL_AF_MODE, mCurrentAfMode);

        repeatingBuilder.set(CaptureRequest.CONTROL_AF_TRIGGER,
                CaptureRequest.CONTROL_AF_TRIGGER_IDLE);
        requestBuilder.set(CaptureRequest.CONTROL_AF_TRIGGER,
                CaptureRequest.CONTROL_AF_TRIGGER_CANCEL);
public synchronized voidupdateCaptureRequest(CaptureRequest.Builder repeatingBuilder)
Update the repeating request with current focus mode.

This is typically used when a new repeating request is created to update preview with new metadata (i.e. crop region). The current auto focus mode needs to be carried over for correct auto focus behavior.

param
repeatingBuilder Builder for a repeating request.

        if (repeatingBuilder == null) {
            throw new IllegalArgumentException("repeatingBuilder shouldn't be null");
        }

        if (mCurrentAfMode == AF_UNINITIALIZED) {
            throw new IllegalStateException("AF mode was not enabled");
        }

        repeatingBuilder.set(CaptureRequest.CONTROL_AF_MODE, mCurrentAfMode);