diff options
| -rw-r--r-- | swapproto.txt | 437 |
1 files changed, 437 insertions, 0 deletions
diff --git a/swapproto.txt b/swapproto.txt new file mode 100644 index 0000000..b32c2d2 --- /dev/null +++ b/swapproto.txt @@ -0,0 +1,437 @@ + 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 <eric@anholt.net> +Dave Airlie <airlied@redhat.com> +Kristian Høgsberg <krh@bitplanet.net> + + ❄ ❄ ❄ ❄ ❄ ❄ ❄ + +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. + + ❄ ❄ ❄ ❄ ❄ ❄ ❄ |