From 921029e55ec3ff90d42905df258046e6f83fa4b6 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Thu, 11 Jul 2013 15:52:50 -0700 Subject: Initial Present protocol specification Signed-off-by: Keith Packard --- Makefile.am | 19 +++ autogen.sh | 12 ++ configure.ac | 13 ++ presentproto.h | 158 ++++++++++++++++++++++++ presentproto.pc.in | 9 ++ presentproto.txt | 351 +++++++++++++++++++++++++++++++++++++++++++++++++++++ presenttokens.h | 47 +++++++ 7 files changed, 609 insertions(+) create mode 100644 Makefile.am create mode 100755 autogen.sh create mode 100644 configure.ac create mode 100644 presentproto.h create mode 100644 presentproto.pc.in create mode 100644 presentproto.txt create mode 100644 presenttokens.h 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 + +#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 +Owen Taylor +James Jones + + ❄ ❄ ❄ ❄ ❄ ❄ ❄ + +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 -- cgit v1.2.1