# CGDisplayStreamFrameAvailableHandler A block called when a data stream has a new frame event to process. ``` 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`](/documentation/CoreGraphics/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 function to retain the surface and the 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 function and then call the 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`](/documentation/CoreGraphics/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 function on the update reference before the end of the handler. When you are finished with the update, call the call the function. This parameter holds `NULL` when the `status` parameter’s has any value other than [`CGDisplayStreamFrameStatus.frameComplete`](/documentation/CoreGraphics/CGDisplayStreamFrameStatus/frameComplete). --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)