Add man pages for libXpresent

Fixes: #1

Signed-off-by: Alan Coopersmith <alan.coopersmith@oracle.com>

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.