diff options
Diffstat (limited to 'presentproto.txt')
| -rw-r--r-- | presentproto.txt | 351 |
1 files changed, 351 insertions, 0 deletions
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. + + ❄ ❄ ❄ ❄ ❄ ❄ ❄ |