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. The choice of whether to use a pixmap buffer or a window buffer depends on the application of the screenshot after it is taken. 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.
The screen_read_window() function captures a screenshot of the window. There are no contraints on the context for this function call, but you must have used either the screen_create_window() function or the screen_create_window_type() function to create the window that's the target of this screenshot. When capturing screenshots of multiple unrelated windows, you will need to make a screen_read_window() function call per window.
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 the function 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 make one screen_read_display() function call per display.