org.freedesktop.cairo

## Class XlibSurface

- Object
- - org.freedesktop.bindings.Pointer
  - - org.freedesktop.bindings.Proxy
    - - org.freedesktop.cairo.Surface
      - - org.freedesktop.cairo.XlibSurface

-     public class XlibSurface
      extends Surface

  A Window as rendered by the X Server. Used internally when drawing to an application window.

  Ordinarily you don't think about creating an XlibSurface; one is implicitly created for you when you create a Cairo context in order to draw in an `Widget.Draw` signal handler:

       gizmo.connect(new Widget.Draw() {
           public boolean onDraw(Widget source, Context cr) {
               Surface surface;

               // start drawing

               // for interest's sake
               surface = cr.getTarget();
               assert (surface instanceof XlibSurface);
           }
       }

  ## Efficient caching of image data

  There is a fair bit of work involved in translating from an image in bitmap form in application memory to the representation that will be used by the X server in video memory. Thus if you are drawing frequently with the same Pixbuf, you may find you are dramatically better off caching the image in the X server.

  The best way to do this is to create an XlibSurface with this image in it. You set that image to be the source pattern with a call to `setSource()` and then paint that onto the Context where you are drawing. The key method involved is `createSimilar()`, which allows you to create an X resource as a cache:

       gizmo.connect(new Widget.Draw() {
           private Surface cache;

           public boolean onDraw(Widget source, Context cr) {
               final Context cr2;
               final Surface target;
               final Pixbuf pixbuf;
               final double x, y;

               // start drawing
               ...

               // cache image
               if (cache == null) {
                   pixbuf = new Pixbuf(filename);

                   target = cr.getTarget();
                   cache = target.createSimilar(Content.COLOR_ALPHA, pixbuf.getWidth(), pixbuf.getHeight());
                   cr2 = new Context(cache);
                   cr2.setSource(pixbuf, 0.0, 0.0);
                   cr2.paint();
               }

               // now we can draw the image
               cr.setSource(cache, x, y);
               cr.paint();
           }
       }

  note that this is not an ImageSurface; we've deliberately created another XlibSurface which is the proxy around the X resource which the X server can decide how best to blit with efficiently.

  Obviously you are consuming X server memory doing this, and it can be overdone. You'll have to look at your application's performance to decide whether this is necessary and if so, how much caching to do. Nevertheless, modern graphics cards are very good at blitting images together so if you are doing anything image intensive you are best to let the X server do the work. Cairo is designed with this in mind.

  Since:
    4.0.7
  Author:
    Andrew Cowie

- - ### Method Summary

    - ### Methods inherited from class org.freedesktop.cairo.Surface

      `copyPage, createSimilar, finish, flush, setMimeData, setMimeData, showPage, writeToPNG`

    - ### Methods inherited from class org.freedesktop.bindings.Pointer

      `toString`

    - ### Methods inherited from class Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`