path: root/swapproto.txt

			  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.

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄