diff options
| -rw-r--r-- | man/Makefile.am | 12 | ||||
| -rw-r--r-- | man/XPresentFreeInput.man | 1 | ||||
| -rw-r--r-- | man/XPresentNotifyMSC.man | 67 | ||||
| -rw-r--r-- | man/XPresentPixmap.man | 167 | ||||
| -rw-r--r-- | man/XPresentQueryCapabilities.man | 73 | ||||
| -rw-r--r-- | man/XPresentQueryExtension.man | 1 | ||||
| -rw-r--r-- | man/XPresentQueryVersion.man | 1 | ||||
| -rw-r--r-- | man/XPresentSelectInput.man | 58 | ||||
| -rw-r--r-- | man/XPresentVersion.man | 1 | ||||
| -rw-r--r-- | man/Xpresent.man | 53 |
10 files changed, 413 insertions, 21 deletions
diff --git a/man/Makefile.am b/man/Makefile.am index 0e9f4a4..5cbf543 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -1,5 +1,5 @@ # -# Copyright (c) 2005, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2005, 2022, Oracle and/or its affiliates. # # Permission is hereby granted, free of charge, to any person obtaining a # copy of this software and associated documentation files (the "Software"), @@ -23,7 +23,15 @@ libmandir = $(LIB_MAN_DIR) -libman_PRE = Xpresent.man +libman_PRE = Xpresent.man \ + XPresentFreeInput.man \ + XPresentNotifyMSC.man \ + XPresentPixmap.man \ + XPresentQueryCapabilities.man \ + XPresentQueryExtension.man \ + XPresentQueryVersion.man \ + XPresentSelectInput.man \ + XPresentVersion.man libman_DATA = $(libman_PRE:man=@LIB_MAN_SUFFIX@) diff --git a/man/XPresentFreeInput.man b/man/XPresentFreeInput.man new file mode 100644 index 0000000..497133e --- /dev/null +++ b/man/XPresentFreeInput.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XPresentSelectInput.__libmansuffix__ diff --git a/man/XPresentNotifyMSC.man b/man/XPresentNotifyMSC.man new file mode 100644 index 0000000..a714d67 --- /dev/null +++ b/man/XPresentNotifyMSC.man @@ -0,0 +1,67 @@ +.\" +.\" +.\" 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. +.\" +.de TQ +.br +.ns +.TP \\$1 +.. +.TH XPresentNotifyMSC __libmansuffix__ __xorgversion__ +.SH NAME +XPresentNotifyMSC \- X Present Extension +.SH SYNTAX +\&#include <X11/extensions/Xpresent.h> +.nf +.sp +void XPresentNotifyMSC \^(\^Display *\fIdisplay\fP, + Window \fIwindow\fP, + uint32_t \fIserial\fP, + uint64_t \fItarget_msc\fP, + uint64_t \fIdivisor\fP, + uint64_t \fIremainder\fP\^)\^; +.fi +.SH DESCRIPTION +.B XPresentNotifyMSC +requests that the X server specified by \fIdisplay\fP +deliver a \fBPresentCompleteNotifyEvent\fP with kind +\fBPresentCompleteKindNotifyMSC\fP after the time specified by +\fItarget-msc\fP, \fIdivisor\fP and \fIremainder\fP. +.PP +\fIserial\fP is an arbitrary client-specified value which will be +returned in the event so that the client can associate the +event and request. +.PP +If \fItarget-msc\fP is greater than the current Media Stream Counter (msc) +for \fIwindow\fP, the event will be delivered at (or after) the \fItarget-msc\fP +field. Otherwise, the event delivery will occur after the next +field where msc % \fIdivisor\fP == \fIremainder\fP. +.PP +If \fIwindow\fP is destroyed before the event is delivered, then +the event delivery will not be completed. +.SH SEE ALSO +.BR Xpresent (__libmansuffix__), +.BR XPresentPixmap (__libmansuffix__), +.BR XPresentQueryCapabilities (__libmansuffix__), +.BR XPresentSelectInput +(__libmansuffix__) +.SH AUTHORS +Keith Packard, Intel diff --git a/man/XPresentPixmap.man b/man/XPresentPixmap.man new file mode 100644 index 0000000..a63f2d1 --- /dev/null +++ b/man/XPresentPixmap.man @@ -0,0 +1,167 @@ +.\" +.\" +.\" 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. +.\" +.de TQ +.br +.ns +.TP \\$1 +.. +.TH XPresentPixmap __libmansuffix__ __xorgversion__ +.SH NAME +XPresentPixmap \- provide pixmap for presentation as window contents +.SH SYNTAX +\&#include <X11/extensions/Xpresent.h> +.nf +.sp +void XPresentPixmap \^(\^Display *\fIdisplay\fP, + Window \fIwindow\fP, + Pixmap \fIpixmap\fP, + uint32_t \fIserial\fP, + XserverRegion \fIvalid\fP, + XserverRegion \fIupdate\fP, + int \fIx_off\fP, + int \fIy_off\fP, + RRCrtc \fItarget_crtc\fP, + XSyncFence \fIwait_fence\fP, + XSyncFence \fIidle_fence\fP, + uint32_t \fIoptions\fP, + uint64_t \fItarget_msc\fP, + uint64_t \fIdivisor\fP, + uint64_t \fIremainder\fP, + XPresentNotify \fI*notifies\fP, + int \fInnotifies\^\fP)\^; +.fi +.SH DESCRIPTION +.B XPresentPixmap +provides new content for the specified \fIwindow\fP, on the X server +specified by \fIdisplay\fP, to be made +visible at the specified time (defined by \fItarget-msc\fP, \fIdivisor\fP +and \fIremainder\fP). If the depth of \fIpixmap\fP and \fIwindow\fP do not +match, a Match error will be generated. +.PP +\fIserial\fP is an arbitrary client-specified value which will +be returned in the associated \fBPresentCompleteNotify\fP event so +that the client can associate the event and request. +.PP +\fIvalid-area\fP defines the portion of \fIpixmap\fP which contains +valid window contents, or None if the pixmap contains valid +contents for the whole window. +.PP +\fIupdate-area\fP defines the subset of the window to be updated, +or None if the whole window is to be updated. +.PP +.B XPresentPixmap +may use any region of \fIpixmap\fP which contains +\fIupdate-area\fP and which is contained by \fIvalid-area\fP. In other +words, areas inside \fIupdate-area\fP will be presented from +\fIpixmap\fP, areas outside \fIvalid-area\fP will not be presented +from \fIpixmap\fP and areas inside \fIvalid-area\fP but outside +\fIupdate-area\fP may or may not be presented at the discretion of +the X server. +.PP +\fIx-off\fP and \fIy-off\fP define the location in the window where +the 0,0 location of the pixmap will be presented. \fIvalid-area\fP +and \fIupdate-area\fP are relative to the pixmap. +.PP +\fIwait-fence\fP and \fIidle-fence\fP are fences from the XSync +extension, which may be created with \fBXSyncCreateFence\fP(). +.PP +The X server will block the presentation action until \fIwait-fence\fP +is triggered, but the +.B XPresentPixmap +function returns immediately. +.PP +When the X server has finished using \fIpixmap\fP for this +operation, it will send a \fBPresentIdleNotify\fP event and arrange +for any \fIidle-fence\fP to be triggered. This may be at any time +following the \fBPresentPixmap\fP 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 +\fBPresentPixmap\fP operation). +.PP +If \fIidle-fence\fP 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 \fIidle-fence\fP is None, then +the X server must arrange for the pixmap to be re-usable by +the client as soon as the \fBPresentIdleNotify\fP event has been +received. Note that if \fBPresentCapabilityFence\fP is set for the +associated CRTC, then clients should use fences to improve +overall system performance. If \fBPresentCapabilityFence\fP is not +set, then using fences offers no benefit, but also no cost. +.PP +If \fItarget-msc\fP is greater than the current msc for \fIwindow\fP, +the presentation will occur at (or after) the \fItarget-msc\fP +field. Otherwise, the presentation will occur after the next +field where msc % \fIdivisor\fP == \fIremainder\fP. +.PP +If \fItarget-crtc\fP is None, then the X server will choose a +suitable CRTC for synchronization. +.PP +If \fIoptions\fP contains \fBPresentOptionAsync\fP, and the \fItarget-msc\fP +is less than or equal to the current Media Stream Counter (msc) for +\fIwindow\fP, then the operation will be performed as soon as possible, not +necessarily waiting for the next vertical blank interval. +.PP +If \fIoptions\fP contains \fBPresentOptionCopy\fP, then \fIpixmap\fP will be +idle, and \fIidle-fence\fP triggered as soon as the operation occurs. +If \fIoptions\fP contains \fBPresentOptionUST\fP, then \fItarget-msc\fP, +\fIdivisor\fP, and \fIremainder\fP 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 \fItarget-crtc\fP supports +\fBPresentCapabilityUST\fP, 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. +.PP +If \fIoptions\fP contains \fBPresentOptionSuboptimal\fP, then the +\fBPresentCompleteNotify\fP event can have mode +\fBPresentCompleteModeSuboptimalCopy\fP as the client supports it. +.PP +After the presentation occurs, a \fBPresentCompleteNotify\fP event +with kind \fBPresentCompleteKindPixmap\fP will be generated, both to +\fIwindow\fP as well as all members of \fInotifies\fP. +\fInotifies\fP is specified as an array of \fBXPresentNotify\fP structures +with \fInnotifies\fP members in the array. +.PP +If \fIwindow\fP is destroyed before the presentation occurs, then +the presentation action will not be completed. +.PP +The X server holds a reference to \fIpixmap\fP until the +presentation occurs, so \fIpixmap\fP may be immediately freed +after the request executes, even if that is before the +presentation occurs. +.PP +If \fIidle-fence\fP is destroyed before the presentation occurs, +then \fIidle-fence\fP will not be signaled but the presentation will +occur normally. +.PP +If \fIwait-fence\fP 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. +.SH SEE ALSO +.BR Xpresent (__libmansuffix__), +.BR XPresentNotifyMSC (__libmansuffix__), +.BR XPresentQueryCapabilities (__libmansuffix__), +.BR XPresentSelectInput (__libmansuffix__) +.SH AUTHORS +Keith Packard, Intel diff --git a/man/XPresentQueryCapabilities.man b/man/XPresentQueryCapabilities.man new file mode 100644 index 0000000..0ee06f1 --- /dev/null +++ b/man/XPresentQueryCapabilities.man @@ -0,0 +1,73 @@ +.\" +.\" +.\" 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. +.\" +.de TQ +.br +.ns +.TP \\$1 +.. +.TH XPresentQueryCapabilities __libmansuffix__ __xorgversion__ +.SH NAME +XPresentQueryCapabilities \- query capabilities of a CRTC +.SH SYNTAX +\&#include <X11/extensions/Xpresent.h> +.nf +.sp +uint32_t XPresentQueryCapabilities \^(\^Display *\fIdisplay\fP, XID \fItarget\fP\^)\^; +.fi +.SH DESCRIPTION +.B XPresentQueryCapabilities +returns a bitmask of the supported capabilities for the target CRTC. If +\fItarget\fP is a CRTC, then it is used as the target CRTC. If +\fItarget\fP is a WINDOW, then the target CRTC is selected by the +X server from among the CRTCs on the screen specified by the window. +.PP +\fBPresentCapabilityAsync\fP 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. +.PP +\fBPresentCapabilityFence\fP means that the target device can take +advantage of SyncFences in the \fBPresent\fP 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. +.PP +\fBPresentCapabilityUST\fP 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 +.BR XPresentPixmap (__libmansuffix__) +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. +.SH SEE ALSO +.BR Xpresent (__libmansuffix__), +.BR XPresentNotifyMSC (__libmansuffix__), +.BR XPresentPixmap (__libmansuffix__), +.BR XPresentSelectInput (__libmansuffix__) +.SH AUTHORS +Keith Packard, Intel diff --git a/man/XPresentQueryExtension.man b/man/XPresentQueryExtension.man new file mode 100644 index 0000000..29ac493 --- /dev/null +++ b/man/XPresentQueryExtension.man @@ -0,0 +1 @@ +.so man__libmansuffix__/Xpresent.__libmansuffix__ diff --git a/man/XPresentQueryVersion.man b/man/XPresentQueryVersion.man new file mode 100644 index 0000000..29ac493 --- /dev/null +++ b/man/XPresentQueryVersion.man @@ -0,0 +1 @@ +.so man__libmansuffix__/Xpresent.__libmansuffix__ diff --git a/man/XPresentSelectInput.man b/man/XPresentSelectInput.man new file mode 100644 index 0000000..a49e740 --- /dev/null +++ b/man/XPresentSelectInput.man @@ -0,0 +1,58 @@ +.\" +.\" +.\" 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. +.\" +.de TQ +.br +.ns +.TP \\$1 +.. +.TH XPresentSelectInput __libmansuffix__ __xorgversion__ +.SH NAME +XPresentSelectInput \- select X Present Extension events to receive +.SH SYNTAX +\&#include <X11/extensions/Xpresent.h> +.nf +.sp +XID XPresentSelectInput \^(\^Display *\fIdisplay\fP, + Window \fIwindow\fP, + unsigned int \fIevent_mask\fP\^)\^; +.sp +void XPresentFreeInput \^(\^Display *\fIdisplay\fP, + Window \fIwindow\fP, + XID \fIevent_id\fP\^)\^; +.fi +.SH DESCRIPTION +.B XPresentSelectInput +selects a set of Present events to be delivered for the +specified \fIwindow\fP on the X server specified by \fIdisplay\fP. +.PP +.B XPresentSelectInput +returns an XID which may be passed to +.B XPresentFreeInput +to stop receiving the requested events. +.SH SEE ALSO +.BR Xpresent (__libmansuffix__), +.BR XPresentNotifyMSC (__libmansuffix__), +.BR XPresentPixmap (__libmansuffix__), +.BR XPresentQueryCapabilities (__libmansuffix__) +.SH AUTHORS +Keith Packard, Intel diff --git a/man/XPresentVersion.man b/man/XPresentVersion.man new file mode 100644 index 0000000..29ac493 --- /dev/null +++ b/man/XPresentVersion.man @@ -0,0 +1 @@ +.so man__libmansuffix__/Xpresent.__libmansuffix__ diff --git a/man/Xpresent.man b/man/Xpresent.man index f615d69..1d17219 100644 --- a/man/Xpresent.man +++ b/man/Xpresent.man @@ -33,36 +33,51 @@ Xpresent \- X Present Extension \&#include <X11/extensions/Xpresent.h> .nf .sp -Bool XPresentQueryExtension \^(\^Display *\fIdpy\fP, +Bool XPresentQueryExtension \^(\^Display *\fIdpy\fP, int *\fImajor_opcode_return\fP, int *\fIevent_base_return\fP, int *\fIerror_base_return\fP\^); .sp Status XPresentQueryVersion \^(\^Display *\fIdpy\fP, int *\fImajor_version_return\fP, int *\fIminor_version_return\fP\^); .sp -void XPresentRegion \^(\^Display *dpy, - Window \fIwindow\fP, - Pixmap \fIpixmap\fP, - uint32_t serial, - XserverRegion valid, - XserverRegion update, - int x_off, - int y_off, - XID idle_fence, - XID target_crtc, - uint64_t target_msc, - uint64_t divisor, - uint64_t remainder); +int XPresentVersion (void); .fi .SH ARGUMENTS -.IP \fIdisplay\fP 1i +.IP \fIdpy\fP 1i Specifies the connection to the X server. -.IP \fIwindow\fP 1i -Specifies which window. .SH DESCRIPTION .B Xpresent -is a library designed to interface the X Present -Extension. +is a library designed to interface the X Present Extension. +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. +The +.B XPresentQueryExtension +function checks if the X server specified by \fIdpy\fP supports the X Present +extension. If the server does not support the extension, it returns False. +If the server does support the extension, it returns True, and sets the +values of \fImajor_opcode_return\fP, \fIevent_base_return\fP, and +\fIerror_base_return\fP if the pointers are not NULL. +.PP +Clients must call the +.B XPresentQueryExtension +function to verify the server supports the extension before calling any other +function for this extension. +The +.B XPresentQueryVersion +function sets the values pointed to by \fImajor_version_return\fP and +\fIminor_version_return\fP to the version of the extension supported +by the X server specified by \fIdpy\fP. +The +.B XPresentQueryVersion +function returns the version of the libXpresent library in use, as defined +by the \fBPRESENT_VERSION\fP macro in <X11/extensions/Xpresent.h>. +.SH SEE ALSO +.BR XPresentNotifyMSC (__libmansuffix__), +.BR XPresentPixmap (__libmansuffix__), +.BR XPresentQueryCapabilities (__libmansuffix__), +.BR XPresentSelectInput (__libmansuffix__) .SH RESTRICTIONS .B Xpresent will remain upward compatible after the 1.0 release. |