NAME¶

XPresentPixmap - provide pixmap for presentation as window contents

SYNTAX¶

#include <X11/extensions/Xpresent.h>

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);

DESCRIPTION¶

XPresentPixmap provides new content for the specified window, on the X server specified by display, 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.

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.

SEE ALSO¶

Xpresent(3), XPresentNotifyMSC(3), XPresentQueryCapabilities(3), XPresentSelectInput(3)

AUTHORS¶

Keith Packard, Intel