SBSDKCameraSession

@interface SBSDKCameraSession : NSObject

An easy-to-use wrapper around the AVFoundations video capture session. Sets up and configures the camera device and the preview layer. Provides functionality to capture still images.

  • The preview layer that the camera device uses to output the current video frames. Can be added to any superlayer.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nonnull) AVCaptureVideoPreviewLayer *previewLayer;

    Swift

    var previewLayer: AVCaptureVideoPreviewLayer { get }

  • Returns the video resolution of the current video output. Orientation is taken into account. Returns CGSizeZero, if the capture session is not running.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CGSize videoResolution;

    Swift

    var videoResolution: CGSize { get }

  • Sets or gets the current video orientation.

    Declaration

    Objective-C

    @property (nonatomic) AVCaptureVideoOrientation videoOrientation;

    Swift

    var videoOrientation: AVCaptureVideoOrientation { get set }

  • Sets or gets the current video frame resolution.

    Declaration

    Objective-C

    @property (nonatomic) SBSDKVideoFrameResolution videoFrameResolution;

    Swift

    var videoFrameResolution: SBSDKVideoFrameResolution { get set }

  • The delegate object for camera output. Its receives the video frames, still image captures and meta data capture, like QR code. Delegates can implement all functions from AVCaptureVideoDataOutputSampleBufferDelegate and AVCaptureMetadataOutputObjectsDelegate protocols.

    Declaration

    Objective-C

    @property (nonatomic, weak, nullable) id<SBSDKCameraSessionDelegate> videoDelegate;

    Swift

    weak var videoDelegate: SBSDKCameraSessionDelegate? { get set }

  • Returns YES if the camera is currently in the process of taking a still image, NO otherwise.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isCapturingStillImage;

    Swift

    var isCapturingStillImage: Bool { get }

  • Returns YES if the camera device has a torch light and the torch light is available.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL torchLightAvailable;

    Swift

    var torchLightAvailable: Bool { get }

  • Turns the torch light on or off.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite,
          getter=isTorchLightEnabled) BOOL torchLightEnabled;

    Swift

    var isTorchLightEnabled: Bool { get set }

  • A block being executed when the torch light status changes (mode or availability).

    Declaration

    Objective-C

    @property (nonatomic, copy, nullable) void (^)(void) updateTorchlightBlock;

    Swift

    var updateTorchlightBlock: (() -> Void)? { get set }

  • A block being executed when the zoom factor has changed. The new zoom factor is provided as parameter.

    Declaration

    Objective-C

    @property (nonatomic, copy, nullable) void (^)(CGFloat) updateZoomBlock;

    Swift

    var updateZoomBlock: ((CGFloat) -> Void)? { get set }

  • The AVCaptureSession object.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) AVCaptureSession *captureSession;

    Swift

    var captureSession: AVCaptureSession? { get }

  • Returns the current cameras exposure settings.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) SBSDKCameraExposureSettings *exposureSettings;

    Swift

    var exposureSettings: SBSDKCameraExposureSettings? { get }

  • The camera devices minimum zoom factor. Readonly.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CGFloat minZoom;

    Swift

    var minZoom: CGFloat { get }

  • The camera devices maximum zoom factor. Readonly.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CGFloat maxZoom;

    Swift

    var maxZoom: CGFloat { get }

  • Sets or gets the camera devices current zoom factor. Zooming is done without animation. If the new value exceeds the minimum or maximum value for zooming it is clamped.

    Declaration

    Objective-C

    @property (nonatomic) CGFloat zoomValue;

    Swift

    var zoomValue: CGFloat { get set }

  • YES, if the camera currently is zooming, NO otherwise.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isZooming;

    Swift

    var isZooming: Bool { get }

  • YES, if zooming is available. No otherwise.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isZoomAvailable;

    Swift

    var isZoomAvailable: Bool { get }

  • Returns YES, if focus lock is enabled, NO otherwise. Readonly.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isFocusLockEnabled;

    Swift

    var isFocusLockEnabled: Bool { get }

  • The prioritization of still image quality and capturing speed. Defaults to SBSDKCapturePhotoQualityPrioritizationBalanced.

    Note: Has no effect on devices prior to iOS 13.0!

    Declaration

    Objective-C

    @property (nonatomic) SBSDKCapturePhotoQualityPrioritization photoQualityPrioritization;

    Swift

    var photoQualityPrioritization: SBSDKCapturePhotoQualityPrioritization { get set }

  • The content mode of the video preview layer: fit-in or fill-in. Defaults to SBSDKVideoContentModeFillIn.

    Declaration

    Objective-C

    @property (nonatomic) SBSDKVideoContentMode videoContentMode;

    Swift

    var videoContentMode: SBSDKVideoContentMode { get set }

  • The camera device to be used.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly, nonnull) SBSDKCameraDevice *device;

    Swift

    var device: SBSDKCameraDevice { get }

  • Returns YES, if the front side camera is used.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isFrontCameraUsed;

    Swift

    var isFrontCameraUsed: Bool { get }

  • The designated initializer of the class. Does not start the capture session.

    Declaration

    Objective-C

    - (nonnull instancetype)initForFeature:(dooFeature)feature;

    Swift

    init(for feature: dooFeature)

    Parameters

    feature

    The feature you want to use the camera for.

    Return Value

    Newly created and configured instance.

  • Extended initializer of the class. Does not start the capture session.

    Declaration

    Objective-C

    - (nullable instancetype)initForFeature:(dooFeature)feature
                             withDevice:(SBSDKCameraDevice *_Nonnull)device;

    Swift

    init?(for feature: dooFeature, with device: SBSDKCameraDevice)

    Parameters

    feature

    The feature you want to use the camera for.
    device

    The camera device to be used.

    Return Value

    Newly created and configured instance or nil, if preset is not supported or setup failed.

  • Starts the camera capture session asynchronously and calls the completion block when finished.

    Declaration

    Objective-C

    - (void)startSession:(void (^_Nullable)(BOOL))completion;

    Swift

    func start() async -> Bool

    Parameters

    completion

    Completion handler with boolean flag, indicating if the session is running or not.

  • Stops the camera capture session. Does nothing if the session is already stopped.

    Declaration

    Objective-C

    - (void)stopSession;

    Swift

    func stop()

  • Returns YES if the camera session has already been started, NO otherwise.

    Declaration

    Objective-C

    - (BOOL)isSessionRunning;

    Swift

    func isSessionRunning() -> Bool

  • Pauses the detection of documents and QR codes.

    Declaration

    Objective-C

    - (void)pauseDetection;

    Swift

    func pauseDetection()

  • Resumes the detection of documents and QR codes.

    Declaration

    Objective-C

    - (void)resumeDetection;

    Swift

    func resumeDetection()

  • Freezes the camera session.

    Declaration

    Objective-C

    - (void)freezeSession;

    Swift

    func freeze()

  • Unfreezes the camera session.

    Declaration

    Objective-C

    - (void)unfreezeSession;

    Swift

    func unfreezeSession()

  • Returns YES, if detection is paused, NO otherwise.

    Declaration

    Objective-C

    - (BOOL)isDetectionPaused;

    Swift

    func isDetectionPaused() -> Bool

  • Captures a still image asynchronously and passes the CMSampleBufferRef and if needed an error to the completion handler. The CMSampleBufferRef can be converted to any image format/object like UIImage.

    Declaration

    Objective-C

    - (void)captureStillImageWithCompletionHandler:
    (nullable void (^)(CVPixelBufferRef _Nullable,
                       NSError *_Nullable))completion;

    Swift

    func captureStillImage() async throws -> CVPixelBuffer

    Parameters

    completion

    The completion handler that is called when the still image has been captured.

  • Captures a still image asynchronously and passes the JPEG image data as NSData and if needed an error to the completion handler.

    Declaration

    Objective-C

    - (void)captureJPEGStillImageWithCompletionHandler:
    (nullable void (^)(NSData *_Nullable, NSError *_Nullable))completion;

    Swift

    func captureJPEGStillImage() async throws -> Data

    Parameters

    completion

    The completion handler that is called when the still image has been captured.

  • Returns YES, if the camera is currently adjusting autofocus, exposure or white balance, NO otherwise.

    Declaration

    Objective-C

    - (BOOL)isCameraAdjusting;

    Swift

    func isCameraAdjusting() -> Bool

  • Sets the camera devices current zoom factor. If the new value exceeds the minimum or maximum value for zooming it is clamped.

    Declaration

    Objective-C

    - (void)setZoomValue:(CGFloat)zoomValue animated:(BOOL)animated;

    Swift

    func setZoomValue(_ zoomValue: CGFloat, animated: Bool)

    Parameters

    zoomValue

    The new zoom factor to be set.
    animated

    If YES, the zooming is animated, otherwise the change is applied without an animation.

  • Resets the zoom factor to the minimum zoom value.

    Declaration

    Objective-C

    - (void)resetZoomAnimated:(BOOL)animated;

    Swift

    func resetZoom(animated: Bool)

    Parameters

    animated

    If YES, the zooming is animated, otherwise the change is applied without an animation.

  • Disables auto-focus and locks the lens at the specified lens position.

    Declaration

    Objective-C

    - (BOOL)beginFocusLockAtLensPosition:(CGFloat)lensPosition;

    Swift

    func beginFocusLock(atLensPosition lensPosition: CGFloat) -> Bool

    Parameters

    lensPosition

    The position of the lens. Values can be between 0.0f (minimum focusing distance) and 1.0f (maximum focusing distance). The value will be clamped to [0.0f, 1.0f].

    Return Value

    YES, if the attempt to lock the focus was successful, NO if the attempt failed or if focus lock is not available.

  • Ends the focus lock and returns to standard continous auto-focus.

    Declaration

    Objective-C

    - (void)endFocusLock;

    Swift

    func endFocusLock()

  • Converts a view space rectangle into the image space of a sample buffer.

    Declaration

    Objective-C

    - (CGRect)transformedRegionOfInterestForViewRect:(CGRect)viewRect
                                  inSampleBuffer:
                                      (nonnull CMSampleBufferRef)sampleBuffer;

    Swift

    func transformedRegionOfInterest(forViewRect viewRect: CGRect, in sampleBuffer: CMSampleBuffer) -> CGRect

    Parameters

    viewRect

    The rectangle to convert in view coordinates of the view the sessions preview layer is attached to.
    sampleBuffer

    The sample buffer into which space the rectangle should be converted.

    Return Value

    The rectangle transformed into the sample buffers image space.