Edit File: presentproto.txt
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. 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, PresentRedirectNotify } PRESENTEVENTMASK { PresentConfigureNotifyMask, PresentCompleteNotifyMask, PresentIdleNotifyMask, PresentSubredirectNotifyMask } 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. ❄ ❄ ❄ ❄ ❄ ❄ ❄ 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. 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, 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 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. ┌─── 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. ❄ ❄ ❄ ❄ ❄ ❄ ❄ 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. ┌─── 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 3 PresentRedirectNotify └─── ┌─── PresentEventMask 1 PresentConfigureNotifyMask 2 PresentCompleteNotifyMask 4 PresentIdleNotifyMask 8 PresentRedirectNotifyMask └─── ┌─── 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.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 └─── ┌─── 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 DRI3 extension defines no errors. ❄ ❄ ❄ ❄ ❄ ❄ ❄
Back to File Manager