Tutorial: Screenshots

Updated: April 19, 2023

Screen screenshots are pixels read from a source and then copied into a buffer. You can then manipulate the buffer as required; it can be simply written to a file or used in other windows or displays.

The Screen API reads pixels from the source and copies them into a provided buffer to capture the screenshot. The buffer can be either a pixmap or a window buffer, but must have the usage flag of type SCREEN_USAGE_NATIVE set. Use a window if you want the content for display; use a pixmap for off-screen usage. For example, you may choose to use a pixmap buffer for your screenshot if you need to capture an image to be used in a different window or on a different display.

Window screenshot

The screen_read_window() function captures a screenshot of the window. There are no constraints on the context for this function call. When capturing screenshots of multiple unrelated windows (i.e., windows that aren't in the same hierarchy), you must call screen_read_window() once per window.

Display screenshot

The screen_read_display() function captures a screenshot of the display. You will need to be working within a privileged context so that you have full access to the display properties of the system. You can create a privileged context by calling screen_create_context() with a context type of SCREEN_DISPLAY_MANAGER_CONTEXT. Your process must have an effective user ID of root to be able to create this context type. When capturing screenshots of multiple displays, you will need to call screen_read_display() once per display.