org.freedesktop.cairo

## Class Surface

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

- Direct Known Subclasses:
    ImageSurface, PdfSurface, SvgSurface, XlibSurface

      public abstract class Surface
      extends org.freedesktop.bindings.Proxy

  The thing that Cairo will draw on/to. This is the base class for several concrete back ends.
  Since:
    4.0.7
  Author:
    Andrew Cowie

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `copyPage()` Emit the current page, but keep the content of the Surface as the starting point for the next page.
    `Surface` | `createSimilar(Content type, int width, int height)` Create a new Surface based on this one.
    `void` | `finish()` Indicate to Cairo that you are finished drawing on this Surface and that it can release the resources that Cairo has used in association with it.
    `void` | `flush()` Complete any pending drawing operations.
    `void` | `setMimeData(MimeType type, byte[] data)` Attach original image data to a surface.
    `void` | `setMimeData(MimeType type, String filename)` Set a filename as the MIME data for this surface.
    `void` | `showPage()` Emit the current page and clear the Surface, allowing you to continue drawing with your Context but to a new blank page.
    `void` | `writeToPNG(String filename)` Output the contents of this Surface to the specified file.

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

      `toString`

    - ### Methods inherited from class Object

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

- - ### Method Detail

    - #### copyPage

          public void copyPage()

      Emit the current page, but keep the content of the Surface as the starting point for the next page.
      Since:
        4.0.10

    - #### createSimilar

          public Surface createSimilar(Content type,
                              int width,
                              int height)

      Create a new Surface based on this one.

           surface.createSimilar(Content.COLOR_ALPHA, 800, 600);

      This has enormous application when drawing with image heavy content to screen.

      Since:
        4.0.10

    - #### finish

          public void finish()

      Indicate to Cairo that you are finished drawing on this Surface and that it can release the resources that Cairo has used in association with it. After you call this, the Surface and any Contexts associated with it will be in-operative.

      While the virtual machine will of course finalize this object when you no longer have strong Java references to it, garbage collection is non-deterministic and often takes place long after drawing is completed. Calling this can allow the underlying library to get on with releasing the resources involved in what is, after all, meant to be a very fast and transient operation.

      Since:
        4.0.7

    - #### flush

          public void flush()

      Complete any pending drawing operations. If your Surface comes from a subsystem whose resources are shared with other drawing libraries, then you need to call this before letting control return to a point where those libraries might draw on the same backing Surface.

      Quoting Carl Worth, the original author of Cairo,

      > This is really only necessary to call if you want to switch from Cairo-based rendering to non-Cairo-based rendering to the same underlying thingy under the Surface (Window, Pixmap, data buffer, etc.).

      In other words, if you are the only one drawing on the Surface, then you don't need this. And that is indeed the case if you are drawing on your own custom Widget in its `Widget.Draw` signal handler.

      See also `finish()` if you're just trying to say "I'm done".

      Clearly, "thingy" is an advanced graphics term.

      Since:
        4.0.7

    - #### setMimeData

          public void setMimeData(MimeType type,
                         byte[] data)

      Attach original image data to a surface. When drawing an image into a vector Surface such as PDF or SVG, Cairo will draw the decoded image as a bitmap. Which is hugely inefficient. This method allows you to add the original image to the surface, and when drawing out Cairo will use this if it can.

      Keep in mind that you attach the data to the intermediate Surface which is painted onto the target, not the final target Surface itself.

           pixbuf = new Pixbuf(data);

           intermediate = new ImageSurface(Format.ARGB32, width, height);

           second = new Context(intermediate);
           second.setSource(pixbuf, 0, 0);
           second.paint();
           intermediate.setMimeData(MimeType.JPEG, data);

           cr.setSource(intermediate, 0, 0);
           cr.paint();

      or you can go through the implicitly created Pattern:

           pixbuf = new Pixbuf(data);

           cr.setSource(pixbuf, 0, 0);
           pattern = cr.getSource();
           implicit = pattern.getSurface();
           implicit.setMimeData(MimeType.JPEG, data);

           cr.paint();

      which seems a bit easier.

      NOTE:
      You must not make any changes to the intermediate surface after setting the image data or you will lose the effect of this call.

      It would be nice if gdk_cairo_set_source_pixbuf() just did this for us.

      Since:
        4.0.18

    - #### setMimeData

          public void setMimeData(MimeType type,
                         String filename)

      Set a filename as the MIME data for this surface.
      Since:
        Unstable

    - #### showPage

          public void showPage()

      Emit the current page and clear the Surface, allowing you to continue drawing with your Context but to a new blank page.

      If you want to render the current page, but keep the page content in your Context, then call `copyPage()` instead.

      This method only applies to Surfaces which are paginated, which in practise means the PDF backend.

      Since:
        4.0.10

    - #### writeToPNG

          public void writeToPNG(String filename)
                          throws IOException

      Output the contents of this Surface to the specified file.
      Throws:
        `IOException` - If the file can't be written.
      Since:
        4.0.7