summaryrefslogtreecommitdiff
path: root/presentproto.txt
diff options
context:
space:
mode:
Diffstat (limited to 'presentproto.txt')
-rw-r--r--presentproto.txt787
1 files changed, 787 insertions, 0 deletions
diff --git a/presentproto.txt b/presentproto.txt
new file mode 100644
index 0000000..fdaf658
--- /dev/null
+++ b/presentproto.txt
@@ -0,0 +1,787 @@
+ 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. Future Present extension versions
+
+This document includes speculation about future 'redirect' support
+within the Present extension. All such information is subject to
+change and is provided only as an aid to further Present development.
+
+1.2. Acknowledgments
+
+Eric Anholt <eric@anholt.net>
+Owen Taylor <otaylor@redhat.com>
+James Jones <jajones@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.
+
+PRESENTNOTIFY {
+ window: WINDOW
+ serial: CARD32
+ }
+
+ A list of these is passed to PresentPixmap; when the indicated
+ PresentPixmap completes, PresentCompletNotify events will be
+ delivered both to the PresentPixmap window/serial parameter as
+ well as each of the entries in the list of PRESENTNOTIFY parameter.
+
+PRESENTEVENTTYPE { PresentConfigureNotify,
+ PresentCompleteNotify,
+ PresentIdleNotify }
+
+PRESENTEVENTMASK { PresentConfigureNotifyMask,
+ PresentCompleteNotifyMask,
+ PresentIdleNotifyMask }
+
+PRESENTOPTION { PresentOptionAsync,
+ PresentOptionCopy,
+ PresentOptionUST }
+
+PRESENTCAPABILITY { PresentCapabilityAsync,
+ PresentCapabilityFence,
+ PresentCapabilityUST }
+
+PRESENTCOMPLETEKIND { PresentCompleteKindPixmap,
+ PresentCompleteKindMSCNotify }
+
+PRESENTCOMPLETEMODE { PresentCompleteModeCopy,
+ PresentCompleteModeFlip,
+ PresentCompleteModeSkip }
+
+The Present extension also uses the Sync extension Fence data type to
+provide synchronization for pixmaps.
+
+2.1. Data Types proposed for a later Present extension version
+
+PRESENTEVENTTYPE { ...
+ PresentRedirectNotify }
+
+PRESENTEVENTMASK { ...
+ PresentSubredirectNotifyMask }
+
+ ❄ ❄ ❄ ❄ ❄ ❄ ❄
+
+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
+PresentPixmap request.
+
+IdleNotify events inform clients when pixmaps are available for re-use.
+
+5.1. Events proposed for a later Present extension version
+
+RedirectNotify events inform clients about other clients PresentPixmap
+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
+
+┌───
+ PresentPixmap
+ window: WINDOW
+ pixmap: PIXMAP
+ serial: CARD32
+ valid-area: REGION or None
+ update-area: REGION or None
+ x-off, y-off: INT16
+ target-crtc: CRTC or None
+ wait-fence: FENCE
+ idle-fence: FENCE
+ options: SETofPRESENTOPTION
+ target-msc: CARD64
+ divisor: CARD64
+ remainder: CARD64
+ notifies: LISTofPRESENTNOTIFY
+└───
+ 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'). If the depth of 'pixmap' and 'window' do not
+ match, a Match error will be generated.
+
+ '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.
+
+ PresentPixmap 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.
+
+ PresentPixmap will block until 'wait-fence' is triggered.
+
+ When the X server has finished using 'pixmap' for this
+ operation, it will send a PresentIdleNotify event and arrange
+ for any 'idle-fence' to be triggered. This may be at any time
+ following the PresentPixmap 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
+ PresentPixmap operation).
+
+ If 'idle-fence' is not None, then the client guarantees to the
+ X server that it will wait for that fence to be signalled
+ before it uses the pixmap again. If 'idle-fence' is None, then
+ the X server must arrange for the pixmap to be re-usable by
+ the client as soon as the PresentIdleNotify event has been
+ received. Note that if PresentCapabilityFence is set for the
+ associated CRTC, then clients should use fences to improve
+ overall systme performance. If PresentCapabilityFence is not
+ set, then using fences offers no benefit, but also no cost.
+
+ 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'.
+
+ If 'target-crtc' is None, then the X server will choose a
+ suitable CRTC for synchronization.
+
+ If 'options' contains PresentOptionAsync, and the 'target-msc'
+ is less than or equal to the current msc for 'window', then
+ the operation will be performed as soon as possible, not
+ necessarily waiting for the next vertical blank interval.
+
+ If 'options' contains PresentOptionCopy, then 'pixmap' will be
+ idle, and 'idle-fence' triggered as soon as the operation occurs.
+
+ If 'options' contains PresentOptionUST, then target-msc,
+ divisor and remainder will all be interpreted as UST values
+ instead of MSC values and the frame update will be scheduled
+ for the specified UST time, If the target-crtc supports
+ PresentCapabilityUST, then the swap time will be as close to
+ the target time as the driver can manage. Otherwise, the
+ server will take the target UST time and convert it to a
+ suitable target MSC value.
+
+ After the presentation occurs, a PresentCompleteNotify event
+ with kind PresentCompleteKindPixmap will be generated, both to
+ 'window' as well as all members of 'notifies'.
+
+ If 'window' is destroyed before the presentation occurs, then
+ the presentation action will not be completed.
+
+ PresentPixmap 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.
+
+ If 'wait-fence' is destroyed before it becomes triggered, then
+ the presentation operation will no longer wait for it and will
+ occur when the other conditions are satisfied.
+
+┌───
+ 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, modify, 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.
+
+┌───
+ PresentQueryCapabilities
+ target: CRTC or WINDOW
+ ▶
+ capabilities: SETofPRESENTCAPABILITY
+└───
+ Errors: Window, CRTC
+
+ Returns the supported capabilities for the target CRTC. If
+ 'target' is a CRTC, then it is used as the target CRTC. If
+ 'target' is a WINDOW, then the target CRTC is selected by the
+ X server from among the CRTCs on the screen specified by the window.
+
+ PresentCapabilityAsync means that the target device can flip
+ the scanout buffer mid-frame instead of waiting for a vertical
+ blank interval. The precise latency between the flip request
+ and the actual scanout transition is not defined by this
+ specification, but is intended to be no more than a few
+ scanlines.
+
+ PresentCapabilityFence means that the target device can take
+ advantage of SyncFences in the Present operations to improve
+ GPU throughput. The driver must operate correctly in the
+ absense of fences, but may have reduced performance. Using
+ fences for drivers not advertising this capability should have
+ no performance impact.
+
+ PresentCapabilityUST means that the target device can scanout
+ the image at an arbitrary UST time value, and is not driven by
+ a periodic scanout timer. Applications specifying UST times
+ for PresentPixmap can expect that their image will appear to
+ the user within a short amount of time from that specified in
+ the request. The precise accuracy of the scanout time is not
+ defined by the extension, but is expected to be on the order
+ of milliseconds or less.
+
+
+7.1 Requests proposed for a later Present extension version
+
+ These are not part of the standard and represent future plans
+ for the Present extension.
+
+┌───
+ PresentSelectInput
+ ...
+└───
+ ...
+
+ Specifying PresentSubredirectNotify Mask causes PresentPixmap
+ 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
+ sequence-number: CARD16
+ length: CARD32 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
+ sequence-number: CARD16
+ length: CARD32 2
+ evtype: PRESENTEVENTTYPE PresentCompleteNotify
+ eventID: PRESENTEVENTID
+ window: WINDOW
+ kind: PRESENTCOMPLETEKIND
+ mode: PRESENTCOMPLETEMODE
+ serial: CARD32
+ ust: CARD64
+ msc: CARD64
+└───
+
+ CompleteNotify events are delivered when a PresentPixmap or
+ PresentNotifyMSC operation has completed.
+
+ 'kind' is PresentCompleteKindPixmap when generated by a
+ PresentPixmap operation completion or
+ PresentCompleteKindNotifyMsc when generated by a
+ PresentNotifyMSC operation completion.
+
+ 'mode' is PresentCompleteModeCopy when the source pixmap
+ contents are taken from the pixmap and the pixmap is idle
+ immediately after the presentation completes. 'mode' is
+ PresentCompleteModeFlip when the pixmap remains in-use even
+ after the presentation completes. It will become idle no later
+ than when the next PresentPixmap operation targeting the same
+ window by any client completes. If the presentation operation
+ was skipped because some later operation made it irrelevant,
+ then 'mode' will be PresentCompleteModeSkip.
+
+ 'serial' is the value provided in the generating PresentPixmap
+ request.
+
+ 'msc' and 'ust' indicate the frame count and system time when
+ the presentation actually occurred.
+
+┌───
+ PresentIdleNotify
+ type: CARD8 XGE event type (35)
+ extension: CARD8 Present extension request number
+ sequence-number: CARD16
+ length: CARD32 0
+ evtype: PRESENTEVENTTYPE PresentIdleNotify
+ eventID: PRESENTEVENTID
+ window: WINDOW
+ serial: CARD32
+ pixmap: PIXMAP
+ idle-fence: FENCE
+└───
+
+ IdleNotify events are delivered when a pixmap used in a
+ PresentPixmap operation may be re-used by the client.
+
+ 'window' is the window from the PresentPixmap to which this
+ event is delivered.
+
+ 'serial' is the value provided in the associated PresentPixmap
+ request.
+
+ 'pixmap' is the pixmap which is ready for re-use.
+
+ 'idle-fence' is the fence which was provided in the
+ originating PresentPixmap request and is used to synchronize
+ rendering between the client and the X server's use of the
+ buffer. If not None, then the client must wait for the fence
+ to be signaled before using the pixmap.
+
+8.1. Extension Events proposed for a later Present extension version
+
+┌───
+ PresentRedirectNotify
+ type: CARD8 XGE event type (35)
+ extension: CARD8 Present extension request number
+ sequence-number: CARD16
+ length: CARD32 17 + 2 n
+ evtype: CARD16 Present_RedirectNotify
+ update-window: BOOL
+
+ eventID: PRESENTEVENTID
+ event-window: WINDOW
+ window: WINDOW
+ pixmap: PIXMAP
+ serial: CARD32
+
+ valid-area: REGION
+ update-area: REGION
+ valid-rect: RECTANGLE
+ update-rect: RECTANGLE
+ x-off, y-off: INT16
+ target-crtc: CRTC
+ wait-fence: FENCE
+ idle-fence: FENCE
+ options: SETofPRESENTOPTION
+ target-msc: CARD64
+ divisor: CARD64
+ remainder: CARD64
+ notifies: LISTofPRESENTNOTIFY
+└───
+
+ RedirectNotify events are delivered when the client has
+ selected for SubredirectNotify the parent of the target
+ window. All of the values provided to the PresentPixmap
+ 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.
+
+ If 'update-window' is TRUE, then there are clients who have
+ requested composite automatic redirect on the window and who
+ presumably expect the window buffer to eventually contain
+ the application provided contents. The compositing manager
+ should at least occasionally update the window buffer with
+ suitable contents. The precise update interval is left to the
+ discretion of the client receiving this event.
+
+ ❄ ❄ ❄ ❄ ❄ ❄ ❄
+
+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
+┌───
+ PresentEventType
+ 0 PresentConfigureNotify
+ 1 PresentCompleteNotify
+ 2 PresentIdleNotify
+└───
+
+┌───
+ PresentEventMask
+ 1 PresentConfigureNotifyMask
+ 2 PresentCompleteNotifyMask
+ 4 PresentIdleNotifyMask
+└───
+
+┌───
+ PresentOption
+ 1 PresentOptionAsync
+ 2 PresentOptionCopy;
+ 4 PresentOptionUST
+└───
+
+┌───
+ PresentCapability
+ 1 PresentCapabilityAsync
+ 2 PresentCapabilityFence
+ 4 PresentCapabilityUST
+└───
+
+┌───
+ PresentCompleteKind
+ 0 PresentCompleteKindPixmap
+ 1 PresentCompleteKindMSCNotify
+└───
+
+┌───
+ PresentCompleteMode
+ 0 PresentCompleteModeCopy
+ 1 PresentCompleteModeFlip
+ 2 PresentCompleteModeSkip
+└───
+
+┌───
+ PresentNotify
+ 4 Window window
+ 4 CARD32 serial
+└───
+
+A.1.1 Common Types proposed for a later Present extension version
+
+┌───
+ PresentEventType
+ ...
+ 3 PresentRedirectNotify
+└───
+
+┌───
+ PresentEventMask
+ ...
+ 8 PresentSubredirectNotifyMask
+└───
+
+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
+└───
+
+┌───
+ PresentPixmap
+ 1 CARD8 major opcode
+ 1 1 Present opcode
+ 2 18+2n length
+ 4 Window window
+ 4 Pixmap pixmap
+ 4 CARD32 serial
+ 4 Region valid-area
+ 4 Region update-area
+ 2 INT16 x-off
+ 2 INT16 y-off
+ 4 CRTC target-crtc
+ 4 SyncFence wait-fence
+ 4 SyncFence idle-fence
+ 4 CARD32 options
+ 4 unused
+ 8 CARD64 target-msc
+ 8 CARD64 divisor
+ 8 CARD64 remainder
+ 8n LISTofPresentNotify notifies
+└───
+
+┌───
+ PresentNotifyMSC
+ 1 CARD8 major opcode
+ 1 2 Present opcode
+ 2 10 length
+ 4 Window window
+ 4 CARD32 serial
+ 4 unused
+ 8 CARD64 target-msc
+ 8 CARD64 divisor
+ 8 CARD64 remainder
+└───
+
+┌───
+ PresentSelectInput
+ 1 CARD8 major opcode
+ 1 3 Present opcode
+ 2 4 length
+ 4 EventID event-id
+ 4 Window window
+ 4 SETofPRESENTEVENTMASK event-mask
+└───
+
+┌───
+ PresentQueryCapabilities
+ 1 CARD8 major opcode
+ 1 4 Present opcode
+ 2 2 length
+ 4 CRTC or Window target
+ ▶
+ 1 1 Reply
+ 1 unused
+ 2 CARD16 sequence number
+ 4 0 reply length
+ 4 SETofPRESENTCAPABILITY capabilities
+└───
+
+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
+ 1 CARD8 kind
+ 1 CARD8 mode
+ 4 CARD32 event id
+ 4 Window window
+ 4 CARD32 serial
+ 8 CARD64 ust
+
+ 8 CARD64 msc
+└───
+
+┌───
+ PresentIdleNotify
+ 1 35 XGE
+ 1 CARD8 Present extension opcode
+ 2 CARD16 sequence number
+ 4 0 length
+ 2 2 PresentIdleNotify
+ 2 unused
+ 4 CARD32 event id
+ 4 Window window
+ 4 CARD32 serial
+ 4 Pixmap pixmap
+ 4 SyncFence idle-fence
+└───
+
+A.3.1 Protocol Events proposed for later Present extension version
+
+┌───
+ PresentRedirectNotify
+ 1 35 XGE
+ 1 CARD8 Present extension opcode
+ 2 CARD16 sequence number
+ 4 18+2n length
+ 2 3 PresentRedirectNotify
+ 1 BOOL update-window
+ 1 unused
+ 4 CARD32 event id
+ 4 Window event-window
+ 4 Window window
+ 4 Pixmap pixmap
+ 4 CARD32 serial
+
+ 4 Region valid-area
+ 4 Region update-area
+ 8 Rectangle valid-rect
+ 8 Rectangle update-rect
+ 2 INT16 x-off
+ 2 INT16 y-off
+ 4 CRTC target-crtc
+ 4 SyncFence wait-fence
+ 4 SyncFence idle-fence
+ 4 CARD32 options
+ 4 unused
+ 8 CARD64 target-msc
+ 8 CARD64 divisor
+ 8 CARD64 remainder
+ 8n LISTofPRESENTNOTIFY notifies
+└───
+
+A.4 Protocol Errors
+
+The Present extension defines no errors.
+
+ ❄ ❄ ❄ ❄ ❄ ❄ ❄