path: root/presentproto.txt

			The Present Extension
			     Version 1.0
			       2013-6-6
      
			    Keith Packard
			  keithp@keithp.com
			  Intel Corporation

1. Introduction

The Present extension provides a way for applications to update their
window contents from a pixmap in a well defined fashion, synchronizing
with the display refresh and potentially using a more efficient
mechanism than copying the contents of the source pixmap.

1.1. Acknowledgments

Eric Anholt <eric@anholt.net>
Owen Taylor <otaylor@redhat.com>
James Jones <janomes@nvidia.com>

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

2. Data Types

PRESENTEVENTID { XID }

	Defines a unique event delivery target for Present
	events. Multiple event IDs can be allocated to provide
	multiple distinct event delivery contexts.

PRESENTEVENTTYPE { PresentConfigureNotify,
		   PresentCompleteNotify,
		   PresentRedirectNotify }

PRESENTEVENTMASK { PresentConfigureNotifyMask,
		   PresentCompleteNotifyMask,
		   PresentSubredirectNotifyMask }

PRESENTCOMPLETEKIND { PresentCompleteKindRegion,
		      PresentCompleteKindMSCNotify }

The Present extension also uses the Sync extension Fence data type to
provide synchronization for pixmaps.

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

3. Errors

EventID
	A value for an EventID argument does not name a defined EventID

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

5. Events

ConfigureNotify events inform clients about window configuration
changes which can affect the allocation of window-related buffers.

CompleteNotify events inform clients about the completion of a pending
PresentRegion request.

RedirectNotify events inform clients about other clients PresentRegion
requests.

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

6. Extension Initialization

The name of this extension is "Present"

┌───
    PresentQueryVersion
	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.

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

7. Extension Requests

┌───
    PresentRegion
	window: WINDOW
	pixmap: PIXMAP
	serial: CARD32
	valid-area: REGION or None
	update-area: REGION or None
	x-off, y-off: INT16
	idle-fence: FENCE
	target-msc: CARD64
	divisor: CARD64
	remainder: CARD64
└───
	Errors: Window, Pixmap, Match

	Provides new content for the specified window, to be made
	visible at the specified time (defined by 'target-msc', 'divisor'
	and 'remainder').

	'serial' is an arbitrary client-specified value which will
	be returned in the associated PresentCompleteNotify event so
	that the client can associate the event and request.

	'valid-area' defines the portion of 'pixmap' which contains
	valid window contents, or None if the pixmap contains valid
	contents for the whole window.

	'update-area' defines the subset of the window to be updated,
	or None if the whole window is to be updated.

	PresentRegion may use any region of 'pixmap' which contains
	'update-area' and which is contained by 'valid-area'. In other
	words, areas inside 'update-area' will be presented from
	'pixmap', areas outside 'valid-area' will not be presented
	from 'pixmap' and areas inside 'valid-area' but outside
	'update-area' may or may not be presented at the discretion of
	the X server.

	'x-off' and 'y-off' define the location in the window where
	the 0,0 location of the pixmap will be presented. valid-area
	and update-area are relative to the pixmap.

	'idle-fence' is triggered when 'pixmap' is no longer in
	use. This may be at any time following the PresentRegion
	request, the contents may be immediately copied to another
	buffer, copied just in time for the vblank interrupt or the
	pixmap may be used directly for display, in which case it will
	be busy until some future PresentRegion operation.

	If 'target-msc' is greater than the current msc for 'window',
	the presentation will occur at (or after) the 'target-msc'
	field. Otherwise, the presentation will occur after the next
	field where msc % 'divisor' == 'remainder'.
	
	After the presentation occurs, a PresentCompleteNotify event
	with kind PresentCompleteKindRegion will be generated.

	If 'window' is destroyed before the presentation occurs, then
	the presentation action will not be completed.

	PresentRegion holds a reference to 'pixmap' until the
	presentation occurs, so 'pixmap' may be immediately freed
	after the request executes, even if that is before the
	presentation occurs.

	If 'idle-fence' is destroyed before the presentation occurs,
	then idle-fence will not be signaled but the presentation will
	occur normally.

┌───
    PresentNotifyMSC
	window: WINDOW
	serial: CARD32
	target-msc: CARD64
	divisor: CARD64
	remainder: CARD64
└───
	Errors: Window

	Delivers a PresentCompleteNotifyEvent with kind
	PresentCompleteKindNotifyMSC after the time specified by
	'target-msc', 'divisor' and 'remainder').

	'serial' is an arbitrary client-specified value which will be
	returned in the event so that the client can associate the
	event and request.

	If 'target-msc' is greater than the current msc for 'window',
	the event will be delivered at (or after) the 'target-msc'
	field. Otherwise, the event delivery will occur after the next
	field where msc % 'divisor' == 'remainder'.
	
	If 'window' is destroyed before the event is delivered, then
	the event delivery will not be completed.

┌───
    PresentSelectInput
	event-id: PRESENTEVENTID
	window: WINDOW
	eventMask: SETofPRESENTEVENT
└───
	Errors: Window, Value, Match, IDchoice, Access

	Selects the set of Present events to be delivered for the
	specified window and event context. PresentSelectInput can
	create, modifiy or delete event contexts. An event context is
	associated with a specific window; using an existing event
	context with a different window generates a Match error.

	If eventContext specifies an existing event context, then if
	eventMask is empty, PresentSelectInput deletes the specified
	context, otherwise the specified event context is changed to
	select a different set of events.

	If eventContext is an unused XID, then if eventMask is empty
	no operation is performed. Otherwise, a new event context is
	created selecting the specified events.

	Specifying PresentSubredirectNotify Mask causes PresentRegion
	requests on any child of 'window' from other clients to
	generate PresentRedirectNotify events to 'window' instead of
	actually performing the operation. However, only one client at
	a time can select for PresentRedirect on a window. An attempt
	to violate this restriction results in an Access error.

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

8. Extension Events

┌───
    PresentConfigureNotify
	type: CARD8			XGE event type (35)
	extension: CARD8		Present extension request number
	length: CARD16			2
	evtype: CARD16			Present_ConfigureNotify
	eventID: PRESENTEVENTID
	window: WINDOW
	x: INT16
	y: INT16
	width: CARD16
	height: CARD16
	off_x: INT16
	off_y: INT16
	pixmap_width: CARD16
	pixmap_height: CARD16
	pixmap_flags: CARD32
└───

	PresentConfigureNotify events are sent when the window
	configuration changes if PresentSelectInput has requested
	it. PresentConfigureNotify events are XGE events and so do not
	have a unique event type.

	'x' and 'y' are the parent-relative location of 'window'. 

┌───
    PresentCompleteNotify
	type: CARD8			XGE event type (35)
	extension: CARD8		Present extension request number
	length: CARD16			2
	evtype: PRESENTEVENTTYPE	PresentCompleteNotify
	eventID: PRESENTEVENTID
	window: WINDOW
	kind: PRESENTCOMPLETEKIND
	serial: CARD32
	ust: CARD64
	msc: CARD64
└───

	CompleteNotify events are delivered when a PresentRegion or
	PresentNotifyMSC operation has completed.

	'kind' is PresentCompleteKindRegion when generated by a
	PresentRegion operation completion or
	PresentCompleteKindNotifyMsc when generated by a
	PresentNotifyMSC operation completion.

	'serial' is the value provided in the generating PresentRegion
	request.

	'msc' and 'ust' indicate the frame count and system time when
	the presentation actually occurred.

┌───
    PresentRedirectNotify
	type: CARD8			XGE event type (35)
	extension: CARD8		Present extension request number
	length: CARD16			2
	evtype: CARD16			Present_RedirectNotify
	eventID: PRESENTEVENTID
	event-window: WINDOW
	window: WINDOW
	pixmap: PIXMAP
	serial: CARD32
	valid-area: REGION
	valid-rect: RECTANGLE
	update-area: REGION
	update-rect: RECTANGLE
	x-off, y-off: INT16
	target_msc: CARD64
	divisor: CARD64
	remainder: CARD64
	idle-fence: FENCE
└───

	RedirectNotify events are delivered when the client has
	selected for SubredirectNotify the parent of the target
	window. All of the values provided to the PresentRegion
	request are provided. If the client simply passes these
	parameters back to the X server, the effect will be as if the
	original client executed the request.


			     ❄ ❄ ❄  ❄  ❄ ❄ ❄

9. Extension Versioning

	1.0: First published version

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄


10. Relationship with other extensions

As an extension designed to support other extensions, there is
naturally some interactions with other extensions.

10.1 GLX

GLX is both an application interface and an X extension. OpenGL
applications using the GLX API will use the GLX extension and may use
the Present extension to display application contents.

10.2 DRI3

The DRI3 extension provides a way to share direct rendered pixel data
with the X server as X pixmaps. When used in conjunction with Present,
they provide a complete direct rendering solution for OpenGL or other
APIs.

10.3 DRI2

Present provides similar functionality to the DRI2SwapBuffers and
requests, however Present uses X pixmaps to refer to the new window
contents instead of the DRI2 buffer attachments.

Present and DRI3 are designed in conjunction to replace DRI2

10.4 XvMC / Xv

It might be nice to be able to use YUV formatted objects as Present
sources.

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄

Appendix A. Protocol Encoding

Syntactic Conventions

This document uses the same syntactic conventions as the core X
protocol encoding document.


A.1 Common Types

A.2 Protocol Requests

┌───
    PresentQueryVersion
	1	CARD8			major opcode
	1	0			Present 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	
└───


A.3 Protocol Events

┌───
    PresentConfigureNotify
	1	35			XGE
	1	CARD8			Present extension opcode
	2	CARD16			sequence number
	4	2			length
	2	0			PresentConfigureNotify
	2				unused
	4	CARD32			event id
	4	Window			window
	2	INT16			x
	2	INT16			y
	2	CARD16			width
	2	CARD16			height
	2	INT16			off x
	2	INT16			off y
	2	CARD16			pixmap width
	2	CARD16			pixmap height
	4	CARD32			pixmap flags
└───

┌───
    PresentCompleteNotify
	1	35			XGE
	1	CARD8			Present extension opcode
	2	CARD16			sequence number
	4	2			length
	2	1			PresentCompleteNotify
	2	CARD16			kind
	4	CARD32			event id
	4	Window			window
	4	CARD32			serial
	8	CARD64			ust
	8	CARD64			msc
└───

A.4 Protocol Errors

The DRI3 extension defines no errors.

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄