Class: AVCaptureDevice

Inherits:
NSObject show all

Overview

An AVCaptureDevice object represents a physical capture device and the properties associated with that device. You use a capture device to configure the properties of the underlying hardware. A capture device also provides input data (such as audio or video) to an AVCaptureSession object.

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from NSObject

#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version

Constructor Details

This class inherits a constructor from NSObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class NSObject

Instance Attribute Details

- (Boolean) adjustingExposure (readonly)

Indicates whether the device is currently adjusting its exposure setting. (read-only)

Returns:

  • (Boolean)

- (Boolean) adjustingFocus (readonly)

Indicates whether the device is currently adjusting its focus setting. (read-only)

Returns:

  • (Boolean)

- (Boolean) adjustingWhiteBalance (readonly)

Indicates whether the devise is currently adjusting the white balance. (read-only)

Returns:

  • (Boolean)

- (Boolean) connected (readonly)

Indicates whether the device is currently connected. (read-only) The value of this property indicates whether the device represented by the receiver is connected and available for use as a capture device. When the value of this property becomes NO for a given instance, however, it will not become YES again. If the same physical device again becomes available to the system, it will be represented using a new instance of AVCaptureDevice.You can observe the value of this property using key-value observing to be notified when a device is no longer available.

Returns:

  • (Boolean)

- (AVCaptureExposureMode) exposureMode

The exposure mode for the device. Before changing the value of this property, you must call lockForConfiguration: to acquire exclusive access to the device’s configuration properties. If you do not, setting the value of this property raises an exception. When you are done configuring the device, call unlockForConfiguration to release the lock and allow other devices to configure the settings.See “AVCaptureExposureMode” for possible values.

Returns:

  • (AVCaptureExposureMode)

- (CGPoint) exposurePointOfInterest

The point of interest for exposure. Before changing the value of this property, you must call lockForConfiguration: to acquire exclusive access to the device’s configuration properties. If you do not, setting the value of this property raises an exception. When you are done configuring the device, call unlockForConfiguration to release the lock and allow other devices to configure the settings.

Returns:

  • (CGPoint)

- (Boolean) exposurePointOfInterestSupported (readonly)

Indicates whether the device supports a point of interest for exposure. (read-only)

Returns:

  • (Boolean)

- (Boolean) flashActive (readonly)

Indicates whether the flash is currently active. (read-only) When the flash is active, it will flash if a still image is captured.You can observe changes to the value of this property using key-value observing.

Returns:

  • (Boolean)

- (Boolean) flashAvailable (readonly)

Indicates whether the flash is currently available for use. (read-only) The flash may become unavailable if, for example, the device overheats and needs to cool off.You can observe changes to the value of this property using key-value observing.

Returns:

  • (Boolean)

- (AVCaptureFlashMode) flashMode

The current flash mode. Before changing the value of this property, you must call lockForConfiguration: to acquire exclusive access to the device’s configuration properties. If you do not, setting the value of this property raises an exception. When you are done configuring the device, call unlockForConfiguration to release the lock and allow other devices to configure the settings.See “AVCaptureFlashMode” for possible values.

Returns:

  • (AVCaptureFlashMode)

- (AVCaptureFocusMode) focusMode

The device’s focus mode. Before changing the value of this property, you must call lockForConfiguration: to acquire exclusive access to the device’s configuration properties. If you do not, setting the value of this property raises an exception. When you are done configuring the device, call unlockForConfiguration to release the lock and allow other devices to configure the settings.See “AVCaptureFocusMode” for possible values.

Returns:

  • (AVCaptureFocusMode)

- (CGPoint) focusPointOfInterest

The point of interest for focusing. Before changing the value of this property, you must call lockForConfiguration: to acquire exclusive access to the device’s configuration properties. If you do not, setting the value of this property raises an exception. When you are done configuring the device, call unlockForConfiguration to release the lock and allow other devices to configure the settings.

Returns:

  • (CGPoint)

- (Boolean) focusPointOfInterestSupported (readonly)

Indicates whether the device supports a point of interest for focus. (read-only)

Returns:

  • (Boolean)

- (Boolean) hasFlash (readonly)

Indicates whether the capture device has a flash. (read-only)

Returns:

  • (Boolean)

- (Boolean) hasTorch (readonly)

A Boolean value that specifies whether the capture device has a torch. (read-only) A torch is a light source, such as an LED flash, that is available on the device and used for illuminating captured content or providing general illumination. This property reflects whether the current device has such illumination hardware built-in. Even if the device has a torch, that torch might not be available for use. Thus, you should also check the value of the torchAvailable property before using it.

Returns:

  • (Boolean)

- (String) localizedName (readonly)

A localized human-readable name for the receiver. (read-only) You can use this property to display the name of a capture device in a user interface.

Returns:

- (String) modelID (readonly)

The model ID of the device. (read-only) The value of this property is an identifier unique to all devices of the same model. The value is persistent across device connections and disconnections, and across different systems. For example, the model ID of the camera built in to two identical iPhone models will be the same even though they are different physical devices.

Returns:

- (AVCaptureDevicePosition) position (readonly)

Indicates the physical position of the device hardware on the system. (read-only) See “AVCaptureDevicePosition” for possible values.

Returns:

  • (AVCaptureDevicePosition)

- (Boolean) subjectAreaChangeMonitoringEnabled

Indicates whether the device should monitor the subject area for changes. The value of this property indicates whether the receiver should monitor the video subject area for changes, such as lighting changes, substantial movement, and so on. If subject area change monitoring is enabled, the capture device object sends an AVCaptureDeviceSubjectAreaDidChangeNotification whenever it detects a change to the subject area, at which time an interested client may wish to re-focus, adjust exposure, white balance, etc.Before changing the value of this property, you must call lockForConfiguration: to acquire exclusive access to the device’s configuration properties. If you do not, setting the value of this property raises an exception. When you are done configuring the device, call unlockForConfiguration to release the lock and allow other devices to configure the settings.

Returns:

  • (Boolean)

- (Boolean) torchActive (readonly)

A Boolean value indicating whether the device’s torch is currently active. (read-only) A torch must be present on the device and currently available before it can be active.

Returns:

  • (Boolean)

- (Boolean) torchAvailable (readonly)

Indicates whether the torch is currently available for use. (read-only) The torch may become unavailable if, for example, the device overheats and needs to cool off.You can observe changes to the value of this property using key-value observing.

Returns:

  • (Boolean)

- (Float) torchLevel (readonly)

The current torch brightness level. (read-only) The value of this property is a floating-point number whose value is in the range 0.0 to 1.0. A torch level of 0.0 indicates that the torch is off. A torch level of 1.0 represents the theoretical maximum value, although the actual maximum value may be lower if the device is currently overheated. You can observe changes to the value of this property using key-value observing.

Returns:

- (AVCaptureTorchMode) torchMode

The current torch mode. Setting the value of this property also sets the torch level to its maximum current value.Before setting the value of this property, call the isTorchModeSupported: method to make sure the device supports the desired mode. Setting the device to an unsupported torch mode results in the raising of an exception. For a list of possible values for this property, see “AVCaptureTorchMode.”Before changing the value of this property, you must call lockForConfiguration: to acquire exclusive access to the device’s configuration properties. If you do not, setting the value of this property raises an exception. When you are done configuring the device, call unlockForConfiguration to release the lock and allow other devices to configure the settings.You can observe changes to the value of this property using key-value observing.

Returns:

  • (AVCaptureTorchMode)

- (String) uniqueID (readonly)

An ID unique to the model of device corresponding to the receiver. (read-only) Every available capture device has a unique ID that persists on one system across device connections and disconnections, application restarts, and reboots of the system itself. You can store the value returned by this property to recall or track the status of a specific device in the future.

Returns:

- (AVCaptureWhiteBalanceMode) whiteBalanceMode

The current white balance mode. Before changing the value of this property, you must call lockForConfiguration: to acquire exclusive access to the device’s configuration properties. If you do not, setting the value of this property raises an exception. When you are done configuring the device, call unlockForConfiguration to release the lock and allow other devices to configure the settings.See “AVCaptureWhiteBalanceMode” for possible values.

Returns:

  • (AVCaptureWhiteBalanceMode)

Class Method Details

+ (AVCaptureDevice) defaultDeviceWithMediaType(mediaType)

Returns the default device used to capture data of a given media type.

Parameters:

  • mediaType (String) —

    A media type identifier.For possible values, see AV Foundation Constants Reference.

Returns:

  • (AVCaptureDevice) —

    The default device used to capture data of the type indicated by mediaType.

+ (Array) devices

Returns an array of the available capture devices on the system.

Returns:

  • (Array) —

    An array containing the available capture devices on the system

+ (Array) devicesWithMediaType(mediaType)

Returns an array of the devices able to capture data of a given media type.

Parameters:

  • mediaType (String) —

    A media type identifier.For possible values, see AV Foundation Constants Reference.

Returns:

  • (Array) —

    An array containing the devices able to capture data of the type indicated by mediaType.

+ (AVCaptureDevice) deviceWithUniqueID(deviceUniqueID)

Returns the device with a given ID.

Parameters:

  • deviceUniqueID (String) —

    The ID of a capture device.

Returns:

Instance Method Details

- (Boolean) hasMediaType(mediaType)

Returns a Boolean value that indicates whether the device provides media with a given type.

Parameters:

  • mediaType (String) —

    A media type, such as AVMediaTypeVideo, AVMediaTypeAudio, or AVMediaTypeMuxed. For a complete list of supported media type constants, see AV Foundation Constants Reference.

Returns:

  • (Boolean) —

    YES if the device provides media of type mediaType, otherwise NO.

- (Boolean) isExposureModeSupported(exposureMode)

Returns a Boolean value that indicates whether the given exposure mode is supported.

Parameters:

  • exposureMode (AVCaptureExposureMode) —

    An exposure mode. See “AVCaptureExposureMode” for possible values.

Returns:

  • (Boolean) —

    YES if exposureMode is supported, otherwise NO.

- (Boolean) isFlashModeSupported(flashMode)

Returns a Boolean value that indicates whether the given flash mode is supported.

Parameters:

  • flashMode (AVCaptureFlashMode) —

    A flash mode. See “AVCaptureFlashMode” for possible values.

Returns:

  • (Boolean) —

    YES if flashMode is supported, otherwise NO.

- (Boolean) isFocusModeSupported(focusMode)

Returns a Boolean value that indicates whether the given focus mode is supported.

Parameters:

  • focusMode (AVCaptureFocusMode) —

    A focus mode. See “AVCaptureFocusMode” for possible values.

Returns:

  • (Boolean) —

    YES if focusMode is supported, otherwise NO.

- (Boolean) isTorchModeSupported(torchMode)

Returns a Boolean value that indicates whether the device supports the specified torch mode.

Parameters:

  • torchMode (AVCaptureTorchMode) —

    The desired torch mode. For a list of possible values, see “AVCaptureTorchMode.”

Returns:

  • (Boolean) —

    YES if torchMode is supported, otherwise NO.

- (Boolean) isWhiteBalanceModeSupported(whiteBalanceMode)

Returns a Boolean value that indicates whether the given white balance mode is supported.

Parameters:

  • whiteBalanceMode (AVCaptureWhiteBalanceMode) —

    A focus mode. See “AVCaptureWhiteBalanceMode” for possible values.

Returns:

  • (Boolean) —

    YES if whiteBalanceMode is supported, otherwise NO.

- (Boolean) lockForConfiguration(outError)

Requests exclusive access to the device’s hardware properties. You must call this method before attempting to configure the hardware related properties of the device. This method returns YES when it successfully locks the device for configuration by your code. After configuring the device properties, call unlockForConfiguration to release the configuration lock and allow other apps to make changes. You may hold onto a lock (instead of releasing it) if you require the device properties to remain unchanged. However, holding the device lock unnecessarily may degrade capture quality in other apps sharing the device.

Parameters:

  • outError (Pointer) —

    On input, specify a pointer to an error object. If a lock cannot be acquired, this pointer contains an NSError object that describes the problem. You may specify nil for this property.

Returns:

  • (Boolean) —

    YES if a lock was acquired or NO if it was not.

- (Boolean) setTorchModeOnWithLevel(torchLevel, error:outError)

Sets the illumination level when in torch mode. This method sets the torch mode to AVCaptureTorchModeOn and sets the level to the specified value. If the device does not support the AVCaptureTorchModeOn torch mode or if you specify a value for torchLevel that is outside the accepted range, this method throws an exception. If the torch value in is within the accepted range but greater than the currently supported maximum—perhaps because the device is overheating—this method simply returns NO. Before changing the value of this property, you must call lockForConfiguration: to acquire exclusive access to the device’s configuration properties. If you do not, this method raises an exception. When you are done configuring the device, call unlockForConfiguration to release the lock and allow other devices to configure the settings.

Parameters:

  • torchLevel (Float) —

    The new torch mode level. This value must be a floating-point number between 0.0 and 1.0. To set the torch mode level to the currently available maximum, specify the constant AVCaptureMaxAvailableTorchLevel for this parameter.

  • outError (Pointer) —

    On input, a pointer to an error object. If an error occurs, this method assigns an error object to the pointer with information about what happened.

Returns:

  • (Boolean) —

    YES if the torch mode level was set or NO if it was not.

- (Boolean) supportsAVCaptureSessionPreset(preset)

Returns a Boolean value that indicates whether the receiver can be used in an capture session configured with the given preset. An AVCaptureSession instance can be associated with a preset that configures its inputs and outputs to fulfill common use cases. You can use this method to determine if the receiver can be used in a capture session with the given preset. For a list of preset constants, see AVCaptureSession Class Reference.

Parameters:

  • preset (String) —

    A capture session preset.

Returns:

  • (Boolean) —

    YES if the receiver can be used with preset, otherwise NO.

- (Object) unlockForConfiguration

Relinquishes exclusive control over the device’s configuration. Call this method to release the lock acquired using the lockForConfiguration: method when you are done configuring the device.

Returns: