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

X Version 11                                    libXpresent 1.0.1                              XPresentPixmap(3)