xpra icon
Bug tracker and wiki

This bug tracker and wiki are being discontinued
please use https://github.com/Xpra-org/xpra instead.

Version 3 (modified by Antoine Martin, 9 years ago) (diff)


Window Refresh

The key feature of xpra is the forwarding of individual window contents to the client.
The speed at which the server compresses and sends screen updates to the client depends on a number of factors. There are only a few things the system can tune at runtime:

  • the "batch delay": this is the time that the server will wait for screen updates to accumulate before grabbing the next frame
  • the video quality (for the x264 video encoder only)
  • the video speed (for the x264 video encoder only)

Code Pointers

Since this is an area that receives constant tuning and improvements, the most reliable source of current information is the code itself:

  • server_source.py: this class is instantiated for each client connection. In particular:
    • GlobalPerformanceStatistics: collects various statistics about this client's connection speed, the various work queues, etc. The get_factors method returns a guesstimate of how the batch delay should be adjusted for the given parameters ("target latency" and "pixel count")
    • calculate_delay_thread which runs at most 4 times a second to tune the batch delay, both the global default one (default_batch_config which is a DamageBatchConfig) and the one specific to each window (see below for details)
  • window_source.py: this class is instantiated for each window and for each client, it deals with sending the window's pixels to the client. In particular:
    • DamageBatchConfig: the structure which encapsulates all the configuration and historical values related to a batch delay.
    • WindowPerformanceStatistics: per-window statistics: performance of the encoding/decoding, amount of frames and pixels in flight, etc. Again, the get_factors method rreturns a guesstimate of how the batch delay should ne agjusted for the given parameters ("pixel_count" and current "batch delay")
  • batch_delay_calculator.py: this class is where we used the factors obtained by get_factors above to tune the various attributes.

Note also that many of these classes have a add_stats method which is used by xpra info to provide detailed statistics from the command line and is a good first step for debugging.

Background on damage request processing

Step by step (and oversimplified - so check the code for details) of the critical damage code path:

  • an X11 client application running against the xpra display updates something on one of its windows, or creates a new window, resizes it, etc. It notifies the X11 server that something needs to be redrawn, changed or updated.
  • xpra, working as a compositing window manager, receives a notification that something needs updating/changing.
  • this Damage event is forwarded through various classes (CompositeHelper, WindowModel, .. and eventually ends up in the server's damage method - often as a Damage event directly, or in other cases we synthesize one to force the client to (re-)draw the window.
  • then for each client connected, we call damage on its ServerSource (see above)
  • then this damage event is forwarded to the WindowSource for the given window (creating one if needed)
  • then we either add this event to the current list of delayed regions (which will expire after "batch delay"), we create a new delayed region, or if things are not congested at all we just process it immediately
  • process_damage_region (called when the timer expires - or directly) will grab the window's pixels and queue a request to call "make a data packet" from it. This is done so that we minimize the amount of work done in the critical UI thread, another thread will pick items off this queue.

The damage thread will pick items from this queue, decide what compression to use, compress the pixels and make a data packet then queue this packet for sending. Note that the queue is in ServerSource and it is shared between all the windows..

Things not covered here:

  • auto-refresh
  • choosing between a full frame or many smaller regions
  • various tunables
  • callbacks recording performance statistics
  • callbacks between ServerSource and WindowSource
  • error handling
  • cancelling requests
  • client encoding options
  • mmap

The Factors