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.
.ns
\\$1 ..
void XPresentPixmap \^(\^Display *display, Window window, Pixmap pixmap, uint32_t serial, XserverRegion valid, XserverRegion update, int x_off, int y_off, RRCrtc target_crtc, XSyncFence wait_fence, XSyncFence idle_fence, uint32_t options, uint64_t target_msc, uint64_t divisor, uint64_t remainder, XPresentNotify *notifies, int nnotifies\^)\^;
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.
XPresentPixmap 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.
wait-fence and idle-fence are fences from the XSync extension, which may be created with XSyncCreateFence().
The X server will block the presentation action until wait-fence is triggered, but the XPresentPixmap function returns immediately.
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 system 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 Media Stream Counter (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. notifies is specified as an array of XPresentNotify structures with nnotifies members in the array.
If window is destroyed before the presentation occurs, then the presentation action will not be completed.
The X server 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.