Contents

CGDisplayStreamFrameAvailableHandler

A block called when a data stream has a new frame event to process.

Declaration

typealias CGDisplayStreamFrameAvailableHandler = (CGDisplayStreamFrameStatus, UInt64, IOSurfaceRef?, CGDisplayStreamUpdate?) -> Void

Discussion

The handler is called whenever the display stream has updated content to process as well as when other events occur. Each time a new frame is generated, the block receives an IOSurface object that contains the pixel data as well as an update object that describes the frame update.

The handler receives the following parameters:

status

Describes the kind of update being passed to the handler. See CGDisplayStreamFrameStatus.

displayTime

The mach absolute time when the event occurred. For a frame event, this is when the frame was displayed by the window server.

frameSurface

An IOSurface object that contains the pixel data. May be NULL in some cases.

If you need to maintain a reference to the surface beyond the lifetime of the handler call, you must call the CFRetain function to retain the surface and the doc://com.apple.documentation/documentation/iosurface/iosurfaceincrementusecount(_:) function to let the display stream know that the frame is not ready for re-use. Once you are finished using the surface you must call the doc://com.apple.documentation/documentation/iosurface/iosurfacedecrementusecount(_:) function and then call the CFRelease function. If you are maintaining a cache of information about the surface (such as a GL texture object created from the surface’s contents), you must not call release it until after you remove it from your cache.

You can not depend on the set of surfaces being used by the display stream as being static, so you should remove surfaces from the cache when they haven’t been re-used in a while.

updateRef

A CGDisplayStreamUpdate reference that holds the update metadata for the current frame.

If you need to hold onto the metadata beyond the lifetime of the handler call, you must call the CFRetain function on the update reference before the end of the handler. When you are finished with the update, call the call the CFRelease function.

This parameter holds NULL when the status parameter’s has any value other than CGDisplayStreamFrameStatus.frameComplete.

See Also

Data Types