The Swap Extension Version 1.0 2013-2-14 Keith Packard keithp@keithp.com Intel Corporation 1. Introduction The Swap extension provides GL SwapBuffers semantics to move pixels from a pixmap to a drawable. This can be used by OpenGL implementations or directly by regular applications. 1.1. Acknowledgments Eric Anholt Dave Airlie Kristian Høgsberg ❄ ❄ ❄ ❄ ❄ ❄ ❄ 2. Data Types The server side region support specified in the Xfixes extension version 2 is used in the SwapRegion request. ❄ ❄ ❄ ❄ ❄ ❄ ❄ 4. Errors No errors are defined by the Swap extension. ❄ ❄ ❄ ❄ ❄ ❄ ❄ 5. Events The Swap extension provides a new event, SwapComplete, to signal when a swap operation has finished. ❄ ❄ ❄ ❄ ❄ ❄ ❄ 6. Protocol Types SWAPSELECTMASK { SwapCompleteMask } Used with SwapSelectInput to specify which events a client is to receive. SWAPIDLE { pixmap: PIXMAP valid: BOOL swap-hi: CARD32 swap-lo: CARD32 } This structure contains information about a pixmap which had been used in a SwapRegion request and which the server is now finished with. If valid is TRUE, swap-hi/swap-lo form a 64-bit swap count value from the SwapRegion request which matches the data that the pixmap currently contains. If valid is FALSE, then the contents of the pixmap are undefined. ❄ ❄ ❄ ❄ ❄ ❄ ❄ 7. Extension Initialization The name of this extension is "Swap". ┌─── SwapQueryVersion client-major-version: CARD32 client-minor-version: CARD32 ▶ major-version: CARD32 minor-version: CARD32 └─── The client sends the highest supported version to the server and the server sends the highest version it supports, but no higher than the requested version. Major versions changes can introduce incompatibilities in existing functionality, minor version changes introduce only backward compatible changes. It is the clients responsibility to ensure that the server supports a version which is compatible with its expectations. Backwards compatible changes included addition of new requests. ❄ ❄ ❄ ❄ ❄ ❄ ❄ 8. Extension Requests ┌─── SwapRegion destination: DRAWABLE region: REGION src-off-x,src-off-y: INT16 source: PIXMAP swap-interval: CARD32 target_msc_hi: CARD32 target_msc_lo: CARD32 divisor_hi: CARD32 divisor_lo: CARD32 remainder_hi: CARD32 remainder_lo: CARD32 ▶ swap_hi: CARD32 swap_lo: CARD32 suggested-x-off,suggested-y-off: INT16 suggested-width,suggested-height: CARD16 idle: LISTofSWAPIDLE └─── Errors: Pixmap, Drawable, Region, Value Schedule a swap of the specified region from the source pixmap to the destination drawable. region specifies the region within the destination to be swapped from the source. src-off-x and src-off-y specify the offset to be added to region to align it with the source pixmap. swap-interval specifies the minimum number of frames since the last SwapRegion request. target_msc_hi/target_msc_lo form a 64-bit value marking the target media stamp count for the swap request. When non-zero, these mark the desired time where the data should be presented. divisor_hi/divisor_lo form a 64-bit value marking the desired media stamp count interval between swaps. remainder_hi/remainder_lo form a 64-bite value marking the desired offset within the divisor_hi/divisor_lo swap interval. In the reply, swap_hi/swap_lo form a 64-bit swap count value when the swap will actually occur (e.g. the last queued swap count + (pending swap count * swap interval)). suggested-width and suggested-height offer a hint as to the best pixmap size to use for full-sized swaps in the future. suggested-x-off and suggested-y-off provide a hint as to where the window contents should be placed within that allocation for future swaps. idle provides a list of pixmaps which were passed in previous SwapRegion requests by this client targeting the same destination. ┌─── SwapSelectInput drawable: DRAWABLE mask: SETofSWAPSELECTMASK └─── Errors: Drawable Selects which Swap events are to be delivered to the requesting client. ┌─── SwapGetMSC drawable: DRAWABLE ▶ ust, msc, sbc: CARD64 └─── Errors: Window Get the current media stamp counter (MSC) and swap buffer count (SBC) along with the unadjusted system time (UST) when the MSC was last incremented. ┌─── SwapWaitMSC drawable: DRAWABLE target_msc: two CARD32s divisor: two CARD32s remainder: two CARD32s ▶ ust, msc, sbc: CARD64 └─── Errors: Window Blocks the client until either the frame count reaches target_msc or, if the frame count is already greater than target_msc when the request is received, until the frame count % divisor = remainder. If divisor is 0, the client will be unblocked if the frame count is greater than or equal to the target_msc. Returns the current media stamp counter (MSC) and swap buffer count (SBC) along with the unadjusted system time (UST) when the MSC was last incremented. ┌─── SwapWaitSBC drawable: DRAWABLE target_sbc: two CARD32s ▶ ust, msc, sbc: CARD64 └─── Errors: Window Blocks the client until the swap buffer count reaches target_sbc. If the swap buffer count is already greater than or equal to target_sbc when the request is recieved, this request will return immediately. If target_sbc is 0, this request will block the client until all previous DRI2SwapBuffers requests have completed. Returns the current media stamp counter (MSC) and swap buffer count (SBC) along with the unadjusted system time (UST) when the MSC was last incremented. ❄ ❄ ❄ ❄ ❄ ❄ ❄ 9. Extension Events ┌─── SwapComplete ▶ drawable: CARD32 ust: CARD64 msc: CARD64 sbc: CARD64 └─── This event is delivered when a SwapRegion operation completes. Note that this may be later than when the SwapRegion request is executed as the operation itself may be delayed until the correct frame count has been reached. ❄ ❄ ❄ ❄ ❄ ❄ ❄ 10. Extension Versioning The Swap extension is adapted from pieces of the DRI2 extension 1.0: First published version ❄ ❄ ❄ ❄ ❄ ❄ ❄ 11. Relationship with other extensions As an extension designed to support other extensions, there is naturally some interactions with other extensions. 11.1 GLX GLX has no direct relation with Swap, but a direct rendering OpenGL application may use GLX to discover 11.2 DRI3 DRI3 provides a mechanism for connecting direct rendering applications with X pixmaps. Those pixmaps can then be used with Swap to provide a complete direct rendering solution for OpenGL or other APIs. 11.3 DRI2 Swap provides similar functionality to the DRI2CopyRegion and DRI2SwapBuffers requests, but uses regular X resources for both source and destination pixel buffers instead of defining new resources. Swap and DRI3 are designed in conjunction to replace DRI2 11.2 XvMC / Xv We might add a DRI2_BUFFER_YUV to do vsynced colorspace conversion blits. ❄ ❄ ❄ ❄ ❄ ❄ ❄ Appendix A. Protocol Encoding Syntactic Conventions This document uses the same syntactic conventions as the core X protocol encoding document. A.1 Common Types ┌─── SWAPIDLE 4 PIXMAP pixmap 1 BOOL valid 3 unused 4 CARD32 swap-hi 4 CARD32 swap-lo └─── A.2 Protocol Requests ┌─── SwapQueryVersion 1 CARD8 major opcode 1 0 Swap opcode 2 3 length 4 CARD32 major version 4 CARD32 minor version ▶ 1 1 Reply 1 unused 2 CARD16 sequence number 4 0 reply length 4 CARD32 major version 4 CARD32 minor version 16 unused └─── ┌─── SwapRegion 1 CARD8 major opcode 1 1 Swap opcode 2 11 length 4 DRAWABLE destination 4 REGION region 2 INT16 src-off-x 2 INT16 src-off-y 4 CARD32 swap-interval 4 CARD32 target_msc_hi 4 CARD32 target_msc_lo 4 CARD32 divisor_hi 4 CARD32 divisor_lo 4 CARD32 remainder_hi 4 CARD32 remainder_lo ▶ 1 1 Reply 1 unused 2 CARD16 sequence number 4 4n reply length 4 CARD32 swap-hi 4 CARD32 swap-lo 2 INT16 suggested-x-off 2 INT16 suggested-y-off 2 CARD16 suggested-width 2 CARD16 suggested-height 8 unused 16n LISTofSWAPIDLE idle └─── ┌─── SwapGetMSC 1 CARD8 major opcode 1 9 Swap opcode 2 8 length 4 DRAWABLE drawable ▶ 1 1 Reply 1 unused 2 CARD16 sequence number 4 0 reply length 4 CARD32 ust_hi 4 CARD32 ust_lo 4 CARD32 msc_hi 4 CARD32 msc_lo 4 CARD32 sbc_hi 4 CARD32 sbc_lo └─── ┌─── SwapWaitMSC 1 CARD8 major opcode 1 10 Swap opcode 2 8 length 4 DRAWABLE drawable 4 CARD32 target_msc_hi 4 CARD32 target_msc_lo 4 CARD32 divisor_hi 4 CARD32 divisor_lo 4 CARD32 remainder_hi 4 CARD32 remainder_lo ▶ 1 1 Reply 1 unused 2 CARD16 sequence number 4 0 reply length 4 CARD32 ust_hi 4 CARD32 ust_lo 4 CARD32 msc_hi 4 CARD32 msc_lo 4 CARD32 sbc_hi 4 CARD32 sbc_lo └─── ┌─── SwapWaitSBC 1 CARD8 major opcode 1 11 Swap opcode 2 8 length 4 DRAWABLE drawable 4 CARD32 swap_hi 4 CARD32 swap_lo ▶ 1 1 Reply 1 unused 2 CARD16 sequence number 4 0 reply length 4 CARD32 ust_hi 4 CARD32 ust_lo 4 CARD32 msc_hi 4 CARD32 msc_lo 4 CARD32 sbc_hi 4 CARD32 sbc_lo └─── A.3 Protocol Events The Swap extension specifies the SwapComplete event. ┌─── SwapComplete 1 CARD8 type 1 CARD8 extension 2 CARD16 sequenceNumber 4 DRAWABLE drawable 4 CARD32 ust_hi 4 CARD32 ust_lo 4 CARD32 msc_hi 4 CARD32 msc_lo 4 CARD32 sbc_hi 4 CARD32 sbc_lo └─── A.4 Protocol Errors The Swap extension specifies no errors. ❄ ❄ ❄ ❄ ❄ ❄ ❄