Initial Present protocol specification

Signed-off-by: Keith Packard <keithp@keithp.com>

7 files changed, 609 insertions, 0 deletions

diff --git a/Makefile.am b/Makefile.am
new file mode 100644
index 0000000..f6a6d3f
--- /dev/null
+++ b/Makefile.am
@@ -0,0 +1,19 @@
+presentdir = $(includedir)/X11/extensions
+present_HEADERS = presentproto.h presenttokens.h
+
+pkgconfigdir = $(libdir)/pkgconfig
+pkgconfig_DATA = presentproto.pc
+
+dist_doc_DATA = presentproto.txt
+
+MAINTAINERCLEANFILES = ChangeLog INSTALL
+
+.PHONY: ChangeLog INSTALL
+
+INSTALL:
+	$(INSTALL_CMD)
+
+ChangeLog:
+	$(CHANGELOG_CMD)
+
+dist-hook: ChangeLog INSTALL
diff --git a/autogen.sh b/autogen.sh
new file mode 100755
index 0000000..904cd67
--- /dev/null
+++ b/autogen.sh
@@ -0,0 +1,12 @@
+#! /bin/sh
+
+srcdir=`dirname $0`
+test -z "$srcdir" && srcdir=.
+
+ORIGDIR=`pwd`
+cd $srcdir
+
+autoreconf -v --install || exit 1
+cd $ORIGDIR || exit $?
+
+$srcdir/configure --enable-maintainer-mode "$@"
diff --git a/configure.ac b/configure.ac
new file mode 100644
index 0000000..2363d30
--- /dev/null
+++ b/configure.ac
@@ -0,0 +1,13 @@
+AC_PREREQ([2.60])
+AC_INIT([PresentProto], [1.0], [https://bugs.freedesktop.org/enter_bug.cgi?product=xorg])
+AM_INIT_AUTOMAKE([foreign dist-bzip2])
+AM_MAINTAINER_MODE
+
+# Require xorg-macros: XORG_DEFAULT_OPTIONS
+m4_ifndef([XORG_MACROS_VERSION],
+          [m4_fatal([must install xorg-macros 1.3 or later before running autoconf/autogen])])
+XORG_MACROS_VERSION(1.3)
+XORG_DEFAULT_OPTIONS
+
+AC_OUTPUT([Makefile
+           presentproto.pc])
diff --git a/presentproto.h b/presentproto.h
new file mode 100644
index 0000000..01fcb67
--- /dev/null
+++ b/presentproto.h
@@ -0,0 +1,158 @@
+/*
+ * Copyright © 2013 Keith Packard
+ *
+ * Permission to use, copy, modify, distribute, and sell this software and its
+ * documentation for any purpose is hereby granted without fee, provided that
+ * the above copyright notice appear in all copies and that both that copyright
+ * notice and this permission notice appear in supporting documentation, and
+ * that the name of the copyright holders not be used in advertising or
+ * publicity pertaining to distribution of the software without specific,
+ * written prior permission.  The copyright holders make no representations
+ * about the suitability of this software for any purpose.  It is provided "as
+ * is" without express or implied warranty.
+ *
+ * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+ * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
+ * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
+ * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
+ * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+ * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
+ * OF THIS SOFTWARE.
+ */
+
+#ifndef _PRESENT_PROTO_H_
+#define _PRESENT_PROTO_H_
+
+#include <X11/extensions/presenttokens.h>
+
+#define Region CARD32
+#define XSyncFence CARD32
+
+typedef struct {
+    CARD8   reqType;
+    CARD8   presentReqType;
+    CARD16  length B16;
+    CARD32  majorVersion B32;
+    CARD32  minorVersion B32;
+} xPresentQueryVersionReq;
+#define sz_xPresentQueryVersionReq   12
+
+typedef struct {
+    BYTE    type;   /* X_Reply */
+    BYTE    pad1;
+    CARD16  sequenceNumber B16;
+    CARD32  length B32;
+    CARD32  majorVersion B32;
+    CARD32  minorVersion B32;
+    CARD32  pad2 B32;
+    CARD32  pad3 B32;
+    CARD32  pad4 B32;
+    CARD32  pad5 B32;
+} xPresentQueryVersionReply;
+#define sz_xPresentQueryVersionReply	32
+
+typedef struct {
+    CARD8   reqType;
+    CARD8   presentReqType;
+    CARD16  length B16;
+    Window  window B32;
+    Pixmap  pixmap B32;
+    Region  valid B32;
+    Region  update B32;
+    INT16   x_off B16;
+    INT16   y_off B16;
+    CARD64  target_msc;
+    CARD64  divisor;
+    CARD64  remainder;
+    XSyncFence idle_fence B32;
+} xPresentRegionReq;
+#define sz_xPresentRegionReq	52
+
+typedef struct {
+    CARD8   reqType;
+    CARD8   presentReqType;
+    CARD16  length B16;
+    CARD32  eid B32;
+    CARD32  window B32;
+    CARD32  eventMask B32;
+} xPresentSelectInputReq;
+#define sz_xPresentSelectInputReq   12
+
+/*
+ * Events
+ *
+ * All Present events are X Generic Events
+ */
+
+typedef struct {
+    CARD8 type;
+    CARD8 extension;
+    CARD16 sequenceNumber B16;
+    CARD32 length;
+    CARD16 evtype B16;
+    CARD16 pad2;
+    CARD32 eid B32;
+    CARD32 window B32;
+    INT16  x B16;
+    INT16  y B16;
+    CARD16 width B16;
+    CARD16 height B16;
+    INT16  off_x B16;
+    INT16  off_y B16;
+
+    CARD16 pixmap_width B16;
+    CARD16 pixmap_height B16;
+    CARD32 pixmap_flags B32;
+} xPresentConfigureNotify;
+#define sz_xPresentConfigureNotify 40
+
+typedef struct {
+    CARD8 type;
+    CARD8 extension;
+    CARD16 sequenceNumber B16;
+    CARD32 length;
+    CARD16 evtype B16;
+    CARD16 pad2 B16;
+    CARD32 eid B32;
+    Window window B32;
+    CARD32 pad3 B32;
+    CARD64 ust;
+    CARD64 msc;
+    CARD64 sbc;
+} xPresentCompleteNotify;
+#define sz_xPresentCompleteNotify 48
+
+typedef struct {
+    CARD8 type;
+    CARD8 extension;
+    CARD16 sequenceNumber B16;
+    CARD32 length;
+    CARD16 evtype B16;
+    CARD16 pad2;
+    CARD32 eid B32;
+
+    Window event_window B32;
+    Window window B32;
+    Pixmap pixmap B32;
+    Region valid_region B32;
+
+    xRectangle valid_rect;
+    xRectangle update_rect;
+
+    Region update_region B32;
+    INT16 x_off B16;
+    INT16 y_off B16;
+    CARD64 target_msc;
+
+    CARD64 divisor;
+    CARD64 remainder;
+
+    XSyncFence idle_fence;
+} xPresentRedirectNotify;
+
+#define sz_xPresentRedirectNotify 84
+
+#undef Region
+#undef XSyncFence
+
+#endif
diff --git a/presentproto.pc.in b/presentproto.pc.in
new file mode 100644
index 0000000..5d328e0
--- /dev/null
+++ b/presentproto.pc.in
@@ -0,0 +1,9 @@
+prefix=@prefix@
+exec_prefix=@exec_prefix@
+libdir=@libdir@
+includedir=@includedir@
+ 
+Name: PresentProto
+Description: Present extension headers
+Version: @PACKAGE_VERSION@
+Cflags: -I${includedir}
diff --git a/presentproto.txt b/presentproto.txt
new file mode 100644
index 0000000..4eed4d8
--- /dev/null
+++ b/presentproto.txt
@@ -0,0 +1,351 @@
+			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.
+
+PRESENTEVENTMASK { PresentConfigureNotifyMask,
+		   PresentCompleteNotifyMask,
+		   PresentSubredirectNotifyMask }
+
+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
+	valid-area: REGION or None
+	update-area: REGION or None
+	x-off, y-off: INT16
+	target-msc: CARD64
+	divisor: CARD64
+	remainder: CARD64
+	idle-fence: FENCE
+└───
+	Errors: Drawable, Pixmap, Match
+
+	Provides new content for the specified window, to be made
+	visible at the specified time (defined by 'target-msc', 'divisor'
+	and 'remainder').
+
+	'update-area' defines the subset of the window to be updated,
+	or None if the whole window is to be updated.
+
+	'valid-area' defines the portion of 'pixmap' which contains
+	valid window contents, or None if the pixmap contains valid
+	contents for the whole window.
+
+	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 '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.
+
+┌───
+    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: CARD16			Present_CompleteNotify
+	eventID: PRESENTEVENTID
+	window: WINDOW
+	ust: CARD64
+	msc: CARD64
+	sbc: CARD64
+└───
+
+	Notify events are delivered when a PresentRegion operation has
+	completed and the specified contents are being displayed. sbc,
+	msc and ust indicate the swap count, frame count and system
+	time of the related PresentRegion request.
+
+┌───
+    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
+	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
+└───
+
+A.4 Protocol Errors
+
+The DRI3 extension defines no errors.
+
+			     ❄ ❄ ❄  ❄  ❄ ❄ ❄
diff --git a/presenttokens.h b/presenttokens.h
new file mode 100644
index 0000000..ba13390
--- /dev/null
+++ b/presenttokens.h
@@ -0,0 +1,47 @@
+/*
+ * Copyright © 2013 Keith Packard
+ *
+ * Permission to use, copy, modify, distribute, and sell this software and its
+ * documentation for any purpose is hereby granted without fee, provided that
+ * the above copyright notice appear in all copies and that both that copyright
+ * notice and this permission notice appear in supporting documentation, and
+ * that the name of the copyright holders not be used in advertising or
+ * publicity pertaining to distribution of the software without specific,
+ * written prior permission.  The copyright holders make no representations
+ * about the suitability of this software for any purpose.  It is provided "as
+ * is" without express or implied warranty.
+ *
+ * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+ * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
+ * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
+ * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
+ * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+ * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
+ * OF THIS SOFTWARE.
+ */
+
+#ifndef _PRESENT_TOKENS_H_
+#define _PRESENT_TOKENS_H_
+
+#define PRESENT_NAME			"Present"
+#define PRESENT_MAJOR			1
+#define PRESENT_MINOR			0
+
+#define PresentNumberErrors		0
+#define PresentNumberEvents		0
+
+#define X_PresentQueryVersion		0
+#define X_PresentRegion			1
+#define X_PresentSelectInput		2
+
+#define PresentNumberRequests		3
+
+#define PresentConfigureNotify	0
+#define PresentCompleteNotify	1
+#define PresentRedirectNotify	2
+
+#define PresentAllEvents   ((1 << PresentConfigureNotify) |     \
+                            (1 << PresentCompleteNotify) |      \
+                            (1 << PresentRedirectNotify))
+
+#endif