summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKeith Packard <keithp@keithp.com>2013-07-11 15:52:50 -0700
committerKeith Packard <keithp@keithp.com>2013-07-11 15:52:50 -0700
commit921029e55ec3ff90d42905df258046e6f83fa4b6 (patch)
tree0b11ac99872ec6aedca27cad069812e2f09f184c
Initial Present protocol specification
Signed-off-by: Keith Packard <keithp@keithp.com>
-rw-r--r--Makefile.am19
-rwxr-xr-xautogen.sh12
-rw-r--r--configure.ac13
-rw-r--r--presentproto.h158
-rw-r--r--presentproto.pc.in9
-rw-r--r--presentproto.txt351
-rw-r--r--presenttokens.h47
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