CBLCameraFocusAndShutter

Objective-C

@protocol CBLCameraFocusAndShutter <NSObject>

Swift

protocol CameraFocusAndShutter : NSObjectProtocol

Camera focus and shutter methods.

Autofocus Setup

  • Returns the current autofocus info from the camera.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) id<CBLFocusInfo> focusInfo;

    Swift

    var focusInfo: (any FocusInfo)? { get }

  • Sets the given AF point as the active point.

    Declaration

    Objective-C

    - (void)setActiveAutoFocusPoint:(nonnull id<CBLFocusPoint>)point
             completionCallback:(nullable CBLErrorableOperationCallback)block;

    Swift

    func setActiveAutoFocusPoint(_ point: any FocusPoint, completionCallback block: ErrorableOperationCallback? = nil)

    Parameters

    point

    The AF point to set as active.
    block

    The block to trigger when the active AF point has been set or an error occurs.

  • Returns YES if the camera currently supports freeform “touch” AF, otherwise NO.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL supportsTouchAF;

    Swift

    var supportsTouchAF: Bool { get }

  • Sets the camera’s touch AF position, if available.

    Declaration

    Objective-C

    - (void)touchAFAtPoint:(CGPoint)center
    completionCallback:(nullable CBLErrorableOperationCallback)block;

    Swift

    func touchAF(at center: CGPoint, completionCallback block: ErrorableOperationCallback? = nil)

    Parameters

    center

    The centre of the touch AF point, expressed in the current live view frame’s aspect.
    block

    The callback to call when the operation is complete.

Engaging Autofocus and Shutter

  • Returns YES if autofocus is currently engaged, otherwise NO.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL autoFocusEngaged;

    Swift

    var autoFocusEngaged: Bool { get }

  • Engages autofocus.

    Note

    Autofocus will remain engaged until disengageAutoFocus: is called. While autofocus is engaged, functionality not directly to taking a shot will be unavailable. Live view (if on before this method is called) will continue to stream, and you can use the engageShutter:, disengageShutter:, and disengageAutoFocus: methods.

    The typical ordering for taking a photograph using these methods is as follows:

    • engageAutoFocus:
    • engageShutter:
    • disengageShutter:

    • disengageAutoFocus:

    Declaration

    Objective-C

    - (void)engageAutoFocus:(nullable CBLErrorableOperationCallback)block;

    Swift

    func engageAutoFocus(_ block: ErrorableOperationCallback? = nil)

    Parameters

    block

    The block to trigger when autofocus has been engaged or an error occurs.

  • Disengages autofocus.

    Declaration

    Objective-C

    - (void)disengageAutoFocus:(nullable CBLErrorableOperationCallback)block;

    Swift

    func disengageAutoFocus(_ block: ErrorableOperationCallback? = nil)

    Parameters

    block

    The block to trigger when autofocus has been disengaged or an error occurs.

  • Returns YES if the shutter is currently engaged, otherwise NO.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL shutterEngaged;

    Swift

    var shutterEngaged: Bool { get }

  • Engages the shutter.

    The shutter will remain “engaged” until disengageShutter: is called. However, if the camera is set to take an exposure of a specific length (i.e., anything other than “bulb” mode) the timing of these calls will have no effect on the exposure.

    Note

    This may not engage autofocus if the camera is configured to use back-button autofocus.

    Note

    Even if you don’t call engageAutoFocus: prior to this method, calling this method may cause autoFocusEngaged to become YES. It is the client’s responsibility to detect this and called disengageAutoFocus: if needed.

    Declaration

    Objective-C

    - (void)engageShutter:(nullable CBLErrorableOperationCallback)block;

    Swift

    func engageShutter(_ block: ErrorableOperationCallback? = nil)

    Parameters

    block

    The block to trigger when the shutter has been engaged or an error occurs.

  • Disengages the shutter.

    Declaration

    Objective-C

    - (void)disengageShutter:(nullable CBLErrorableOperationCallback)block;

    Swift

    func disengageShutter(_ block: ErrorableOperationCallback? = nil)

    Parameters

    block

    The block to trigger when the shutter has been disengaged or an error occurs.

  • Takes a single photo.

    This method will (optionally) engage autofocus, engage the shutter, disengage the shutter and disengage autofocus. Think of it as a “Take a photo!” button.

    Declaration

    Objective-C

    - (void)
    invokeOneShotShutterExplicitlyEngagingAutoFocus:(BOOL)triggerAutoFocus
                                 completionCallback:
                                     (nullable CBLErrorableOperationCallback)
                                         block;

    Swift

    func invokeOneShotShutterExplicitlyEngagingAutoFocus(_ triggerAutoFocus: Bool, completionCallback block: ErrorableOperationCallback? = nil)

    Parameters

    triggerAutoFocus

    Pass YES to explicitly engage autofocus during the process, otherwise NO.
    block

    The block to trigger when the operation completes or an error occurs.

Camera-Initiated Transfer

  • Adds an observer to be notified when a camera-initiated transfer request is received.

    Note

    Only cameras that support the CBLCameraSupportedFunctionalityCameraInitiatedTransfer functionality flag will trigger these callbacks.

    Declaration

    Objective-C

    - (nonnull CBLCameraObserverToken *)addCameraInitiatedTransferHandler:
    (nonnull CBLCameraInitiatedTransferRequestHandler)handler;

    Swift

    func addCameraInitiatedTransferHandler(_ handler: @escaping CameraInitiatedTransferRequestHandler) -> String

    Parameters

    handler

    The handler to be called when a camera-initiated transfer request is received. Will be called on the main thread.

  • Removes a previously registered camera-initiated transfer handler.

    Declaration

    Objective-C

    - (void)removeCameraInitiatedTransferHandlerWithToken:
    (nonnull CBLCameraObserverToken *)token;

    Swift

    func removeCameraInitiatedTransferHandler(with token: String)

    Parameters

    token

    The token for the hander to be removed.

Direct Focus Manipulation

  • Drive the camera’s focus a certain amount in the given direction. Requires that the camera has the CBLCameraSupportedFunctionalityDirectFocusManipulation functionality available.

    Direct focus manipulation with this method requires that the camera has live view enabled, and that autofocus is engaged. If the camera isn’t in the correct state, an error of CBLErrorCodeNotAvailable will be returned. In some situations, you may receive an error of CBLErrorCodeFocusDidNotMove — this indicates that either the focus is already at the end of its travel in the specified direction, or that the focus didn’t move for some other reason.

    Declaration

    Objective-C

    - (void)driveFocusByAmount:(CBLFocusDriveAmount)amount
               inDirection:(CBLFocusDriveDirection)direction
        completionCallback:(nullable CBLErrorableOperationCallback)callback;

    Swift

    func driveFocus(amount: FocusDriveAmount, direction: FocusDriveDirection, completionCallback callback: ErrorableOperationCallback? = nil)

    Parameters

    amount

    The amount to move the focus. The actual change in focus will depend on the camera and lens being used.
    direction

    The direction in which the focus should move.
    callback

    The block to trigger when the operation completes or an error occurs.