Use buffer sharing when you want a window to show the same content as a display.
When screen_share_display_buffers() is called, the framebuffer is what's shared with the window. When the display hardware supports write-back, the function screen_share_display_buffers() creates new buffers, if necessary, to account for size, pixel format, or to organize the content Display hardware that supports write-back triggers the creation of new buffers and copies the framebuffer's content to these new buffers. This behavior is different from screen_share_window_buffers() because when windows share buffers, the buffers are only shared, and no buffers are ever created.
Figure 1. A display sharing buffers with a window
Generally for displays, the framebuffer is shared because displays aren't associated with any actual buffers themselves. When there isn't already an existing framebuffer and one's needed, then a framebuffer is created according to the configuration that was specified in graphics.conf when Screen was started. If you didn't configure a framebuffer class in graphics.conf, then an error is returned and errno is set to ENOTSUP when you try to share display buffers.
When windows share buffers, only the properties of the window that owns the buffer are applied. However, when a window shares buffers with a display, the window's properties, such as, SCREEN_PROPERTY_FORMAT and SCREEN_PROPERTY_SWAP_INTERVAL, are considered because the display has no buffers of its own. So the rate at which the window is updated could differ from the original display's refresh rate. For example, if you set the SCREEN_PROPERTY_SWAP_INTERVAL property to 0, you're indicating that the window buffers are to be updated when the display is updated. If you set the SCREEN_PROPERTY_SWAP_INTERVAL property to 1, then the window buffers are to be updated at the refresh rate of the display, even if nothing's been changed on the display. It's important to set an appropriate swap interval, as you don't want to be updating your window buffers more than absolutely necessary.
An alternative to sharing display buffers is to use the function screen_read_display(). Usually, this function is used if you just need a one-time screenshot of the display. Your buffer isn't updated if the display changes after you've called screen_read_display().