| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/QTKit.framework |
| Availability | Available in QuickTime 7.2.1 and later. |
| Declared in | QTCaptureDecompressedVideoOutput.h |
This class represents an output destination for a QTCaptureSession object that can be used to process decompressed frames from the video being captured. Instances of QTCaptureDecompressedVideoOutput produce decompressed video frames suitable for high-quality processing. Because instances maintain maximum frame quality and avoid dropping frames, using this output may result in reduced performance while capturing. Applications that need to process decompressed frames but can tolerate dropped frames or drops in decompression quality should use QTCaptureVideoPreviewOutput instead. Applications can access the decompressed frames via the captureOutput:didOutputVideoFrame:withSampleBuffer:fromConnection: delegate method. Clients can also create subclasses of QTCaptureDecompressedVideoOutput to add custom capturing behavior.
– automaticallyDropsLateVideoFrames
– delegate
– setDelegate:
– setMinimumVideoFrameInterval:
– outputVideoFrame:withSampleBuffer:fromConnection:
– minimumVideoFrameInterval
– pixelBufferAttributes
– setAutomaticallyDropsLateVideoFrames:
– setPixelBufferAttributes:
– captureOutput:didDropVideoFrameWithSampleBuffer:fromConnection: delegate method
– captureOutput:didOutputVideoFrame:withSampleBuffer:fromConnection: delegate method
Returns whether the receiver discards video frames that are output before earlier frames have been processed.
- (BOOL)automaticallyDropsLateVideoFrames
This method returns YES if the receiver drops late video frames and returns NO otherwise.
If this method returns YES, the receiver will discard frames that are queued up while the thread handling existing frames is blocked in the outputVideoFrame:withSampleBuffer:fromConnection: or the captureOutput:didDropVideoFrameWithSampleBuffer:fromConnection: delegate method. The delegate method captureOutput:didDropVideoFrameWithSampleBuffer:fromConnection: will be called for each frame that is dropped. The default value is NO.
QTCaptureDecompressedVideoOutput.hReturns the receiver’s delegate.
- (id)delegate
QTCaptureDecompressedVideoOutput.hReturns the minimum time interval between which the receiver will output consecutive video frames.
- (NSTimeInterval)minimumVideoFrameInterval
An NSTimeInterval specifying the minimum interval between video frames. Returns 0 if there is no frame rate limit set.
This method returns the minimum amount of time that should separate consecutive frames output by the receiver. This is equivalent to the inverse of the maximum frame rate. A value of 0 indicates an unlimited maximum frame rate. The default value is 0.
QTCaptureDecompressedVideoOutput.hCalled whenever the receiver outputs a new video frame.
- (void)outputVideoFrame:(CVImageBufferRef)videoFrame withSampleBuffer:(QTSampleBuffer *)sampleBuffer fromConnection:(QTCaptureConnection *)connection
A Core Video buffer containing the decompressed frame.
A sample buffer containing additional information about the frame, such as its presentation time.
The connection from which the video was received.
This method should not be invoked directly. Subclasses can override this method to provide custom processing behavior for each frame. The default implementation calls the delegate’s captureOutput:didOutputVideoFrame:withSampleBuffer:fromConnection: method. Subclasses should not assume that this method will be called on the main thread. In addition, this method is called periodically, so it must be efficient to prevent capture performance problems.
In order to promptly reclaim memory resources, after this method returns, the sample data contained within the QTSampleBuffer object will be released using its decrementSampleUseCount method. Clients that reference the sample buffer and are interested in the sample data that it contains after this method returns should call incrementSampleUseCount on the sample buffer within this method to ensure that the data remains valid until they no longer need it (at which time they should call decrementSampleUseCount). Clients that reference the sample buffer after this method returns, but only need access to its metadata, such as duration, presentation time, and other attributes, need not call incrementSampleUseCount.
Note that to maintain optimal performance, some sample buffers directly reference pools of memory that may need to be reused by the device system and other capture inputs. This is frequently the case for uncompressed device native capture where memory blocks are copied as little as possible. If multiple sample buffers reference such pools of memory for too long, inputs will no longer be able to copy new samples into memory and those samples will be dropped. If your application is causing samples to be dropped by holding on to sample data for too long using incrementSampleUseCount, but it needs access to the sample data for a long period of time, consider copying the data into a new buffer and then calling decrementSampleUseCount on the sample buffer so that the memory it references can be reused.
QTCaptureDecompressedVideoOutput.hReturns the Core Video pixel buffer attributes previously set by setPixelBufferAttributes: that determine what kind of pixel buffers are output by the receiver.
- (NSDictionary *)pixelBufferAttributes
A dictionary containing pixel buffer attributes for buffers output by the receiver. The keys in the dictionary are described in CoreVideo/CVPixelBuffer.h. If the return value is NIL, then the receiver outputs buffers using the fastest possible pixel buffer attributes.
This method returns the pixel buffer attributes set by setPixelBufferAttributes: that clients can use to customize the size and pixel format of the video frames output by the receiver. When the dictionary is non-nil, the receiver will attempt to output pixel buffers using the attributes specified in the dictionary. A non-nil dictionary also guarantees that the output CVImageBuffer is a CVPixelBuffer. When the value for kCVPixelBufferPixelFormatTypeKey is set to an NSNumber, all image buffers output by the receiver will be in that format. When the value is an NSArray, image buffers output by the receiver will be in the most optimal format specified in that array. If the captured images are not in the one of the specified pixel formats, then a format conversion will be performed. If the dictionary is NIL or there is no value for the kCVPixelBufferPixelFormatTypeKey, then the receiver will output images in the most efficient possible format given the input. For example, if the source is an iSight producing component Y'CbCr 8-bit 4:2:2 video then Y'CbCr 8-bit 4:2:2 will be used as the output format in order to avoid any conversions. The default value for the returned dictionary is NIL.
QTCaptureDecompressedVideoOutput.hSets whether the receiver discards video frames that are output before earlier frames have been processed.
- (void)setAutomaticallyDropsLateVideoFrames:(BOOL)automaticallyDropsLateVideoFrames
Whether the receiver should drop late video frames.
Setting this to YES will cause the receiver to discard frames that are queued up while the thread handling existing frames is blocked in the outputVideoFrame:withSampleBuffer:fromConnection: or the captureOutput:didDropVideoFrameWithSampleBuffer:fromConnection: delegate method. The delegate method captureOutput:didDropVideoFrameWithSampleBuffer:fromConnection: will be called for each frame that is dropped. The default value is NO.
QTCaptureDecompressedVideoOutput.hSets the receiver’s delegate.
- (void)setDelegate:(id)delegate
QTCaptureDecompressedVideoOutput.hSets the minimum time interval between which the receiver should output consecutive video frames.
- (void)setMinimumVideoFrameInterval:(NSTimeInterval)minimumVideoFrameInterval
An NSTimeInterval specifying the minimum interval between video frames. A value of 0 indicates that there should be no frame rate limit.
This method sets the minimum amount of time that should separate consecutive frames output by the receiver. This is equivalent to the inverse of the maximum frame rate. A value of 0 indicates an unlimited maximum frame rate. The default value is 0.
QTCaptureDecompressedVideoOutput.hSets the CoreVideo pixel buffer attributes that determine what kind of pixel buffers are output by the receiver.
- (void)setPixelBufferAttributes:(NSDictionary *)pixelBufferAttributes
A dictionary containing pixel buffer attributes for buffers that will be output by the receiver. The keys in the dictionary are described in CoreVideo/CVPixelBuffer.h. If the dictionary is NIL, then the receiver outputs buffers using the fastest possible pixel buffer attributes.
This method sets the pixel buffer attributes that clients can use to customize the size and pixel format of the video frames output by the receiver. When the dictionary is non-nil, the receiver will attempt to output pixel buffers using the attributes specified in the dictionary. A non-nil dictionary also guarantees that the output CVImageBuffer is a CVPixelBuffer. When the value for kCVPixelBufferPixelFormatTypeKey is set to an NSNumber, all image buffers output by the receiver will be in that format. When the value is an NSArray, image buffers output by the receiver will be in the most optimal format specified in that array. If the captured images are not in the one of the specified pixel formats, then a format conversion will be performed. If the dictionary is NIL or there is no value for the kCVPixelBufferPixelFormatTypeKey, then the receiver will output images in the most efficient possible format given the input. For example, if the source is an iSight producing component Y'CbCr 8-bit 4:2:2 video then Y'CbCr 8-bit 4:2:2 will be used as the output format in order to avoid any conversions.
QTCaptureDecompressedVideoOutput.hCalled once for each frame that is dropped when automaticallyDropsLateVideoFrames is set to YES.
- (void)captureOutput:(QTCaptureOutput *)captureOutput didDropVideoFrameWithSampleBuffer:(QTSampleBuffer *)sampleBuffer fromConnection:(QTCaptureConnection *)connection
The QTCaptureDecompressedVideoOutput instance that dropped the late video frame.
A QTSampleBuffer instance containing metadata about the dropped frame, such as its duration and presentation time stamp. This sample buffer will contain none of the original video data, and accessing its bytesForAllSamples method is invalid and will throw an exception.
The connection from which the dropped video frame was received.
When automaticallyDropsLateVideoFrames is set to YES, this method is called whenever a late video frame is dropped. This method is called once for each dropped frame and may be called before the call to the outputVideoFrame:withSampleBuffer:fromConnection: or the captureOutput:didDropVideoFrameWithSampleBuffer:fromConnection: delegate method during which those frames were dropped returns. The QTSampleBuffer object passed to this delegate method will contain metadata about the dropped video frame, such as its duration and presentation time stamp, but will contain no actual video data. Delegates should not assume that this method will be called on the main thread. Because this method may be called on the same thread that is responsible for outputting video frames, it must be efficient to prevent further capture performance problems, such as additional dropped video frames.
QTCaptureDecompressedVideoOutput.hCalled whenever the video preview output outputs a new video frame.
- (void)captureOutput:(QTCaptureOutput *)captureOutput didOutputVideoFrame:(CVImageBufferRef)videoFrame withSampleBuffer:(QTSampleBuffer *)sampleBuffer fromConnection:(QTCaptureConnection *)connection
The QTCaptureDecompressedVideoOutput instance that output the frame.
A Core Video image buffer containing the decompressed frame.
A sample buffer containing additional information about the frame, such as its presentation time.
The connection from which the video was received.
Delegates receive this message whenever the output decompresses and outputs a new video frame. Delegates can use the provided video frame for a custom preview or for further image processing. Delegates should not assume that this method will be called on the main thread. In addition, this method is called periodically, so it must be efficient to prevent capture performance problems.
In order to promptly reclaim memory resources, after this method returns, the sample data contained within the QTSampleBuffer object will be released using its decrementSampleUseCount method. Clients that reference the sample buffer and are interested in the sample data that it contains after this method returns should call incrementSampleUseCount on the sample buffer within this method to ensure that the data remains valid until they no longer need it (at which time they should call decrementSampleUseCount). Clients that reference the sample buffer after this method returns, but only need access to its metadata, such as duration, presentation time, and other attributes, need not call incrementSampleUseCount.
Note that to maintain optimal performance, some sample buffers directly reference pools of memory that may need to be reused by the device system and other capture inputs. This is frequently the case for uncompressed device native capture where memory blocks are copied as little as possible. If multiple sample buffers reference such pools of memory for too long, inputs will no longer be able to copy new samples into memory and those samples will be dropped. If your application is causing samples to be dropped by holding on to sample data for too long using incrementSampleUseCount, but it needs access to the sample data for a long period of time, consider copying the data into a new buffer and then calling decrementSampleUseCount on the sample buffer so that the memory it references can be reused.
QTCaptureDecompressedVideoOutput.hLast updated: 2010-01-26