Current File : //usr/share/doc/xorgproto/presentproto.txt
The Present Extension
Version 1.2
2018-02-26
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>
Louis-Francis Ratté-Boulianne <lfrb@collabora.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,
PresentOptionSuboptimal }
PRESENTCAPABILITY { PresentCapabilityAsync,
PresentCapabilityFence,
PresentCapabilityUST }
PRESENTCOMPLETEKIND { PresentCompleteKindPixmap,
PresentCompleteKindMSCNotify }
PRESENTCOMPLETEMODE { PresentCompleteModeCopy,
PresentCompleteModeFlip,
PresentCompleteModeSkip,
PresentCompleteModeSuboptimalCopy }
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.
If 'options' contains PresentOptionSuboptimal, then the
PresentCompleteNotify event can have mode
PresentCompleteModeSuboptimalCopy as the client supports it.
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
absence 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
PresentCompleteModeSuboptimalCopy when the source pixmap
contents are copied but it would be possible to flip the
pixmap if the buffer format/modifier was different (options
given to PresentPixmap must contain PresentOptionSuboptimal).
'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
1.2: Added PresentCompleteModeSuboptimalCopy flag and
PresentOptionSuboptimal option
❄ ❄ ❄ ❄ ❄ ❄ ❄
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
8 PresentOptionSuboptimal
└───
┌───
PresentCapability
1 PresentCapabilityAsync
2 PresentCapabilityFence
4 PresentCapabilityUST
└───
┌───
PresentCompleteKind
0 PresentCompleteKindPixmap
1 PresentCompleteKindMSCNotify
└───
┌───
PresentCompleteMode
0 PresentCompleteModeCopy
1 PresentCompleteModeFlip
2 PresentCompleteModeSkip
3 PresentCompleteModeSuboptimalCopy
└───
┌───
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.
❄ ❄ ❄ ❄ ❄ ❄ ❄
Mini Shell