--- name: "XPresentPixmap" section: "3" platform: "linux" package: "libxpresent" version: "1.0.2-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/XPresentPixmap" --- # XPresentPixmap(3) provide pixmap for presentation as window contents ## NAME XPresentPixmap - provide pixmap for presentation as window contents ## SYNTAX \#include \ ``` 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)](/Xpresent/3.md), [**XPresentNotifyMSC**(3)](/XPresentNotifyMSC/3.md), [**XPresentQueryCapabilities**(3)](/XPresentQueryCapabilities/3.md), [**XPresentSelectInput**(3)](/XPresentSelectInput/3.md) ## AUTHORS Keith Packard, Intel