Returns a composite image of the specified windows.


init?(windowListFromArrayScreenBounds screenBounds: CGRect, windowArray: CFArray, imageOption: CGWindowImageOption)



The rectangle that you want to capture. The coordinates of the rectangle must be specified in screen coordinates, where the screen origin is in the upper-left corner of the main display and y-axis values increase downward. Specify null to indicate the minimum rectangle that encloses the specified windows. Specify infinite to capture the entire desktop area.


An array of CGWindowID types, each of which corresponds to a window whose information you want to retrieve. The order of the window IDs also affects the compositing order of the windows; see the discussion for more information about this behavior.


The options that determine which parts of the window to capture. If you specified null for the screenBounds parameter, these options help determine the resulting bounding box used for the image. For example, if you include a window’s screen effects in the image, the bounding box may need to be slightly larger to accommodate those effects. For a list of possible options, see Window Image Types.

Return Value

A composite image formed from the contents of the specified set of windows. Invalid window IDs are ignored. If the windows are unreadable (because their sharing setting is set to CGWindowSharingType.none, for example) or if no windows meet the specified criteria, this function returns an image that is either 0 by 0 pixels in size or is of the specified size but is filled with the transparent black color. If you call this function from outside of a GUI security session or when no window server is running, this function returns NULL.


This function ignores any window IDs in the windowArray parameter that refer to windows that no longer exist. (This can occur if the user closes a window between the time you retrieve its ID and the time you call this function.) If this results in no windows being available in the selected range, this function returns NULL.

This function ignores the onscreen ordering of the windows and instead composites them using the order specified in the windowArray parameter. In other words, windows at the beginning of the array are composited in front of windows at the end of the array.

See Also

Getting Window Information

func CGWindowListCopyWindowInfo(CGWindowListOption, CGWindowID) -> CFArray?

Generates and returns information about the selected windows in the current user session.

func CGWindowListCreateDescriptionFromArray(CFArray?) -> CFArray?

Generates and returns information about windows with the specified window IDs.

func CGWindowListCreateImage(CGRect, CGWindowListOption, CGWindowID, CGWindowImageOption) -> CGImage?

Returns a composite image based on a dynamically generated list of windows.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software