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

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.ExposeEvent 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

Overview  Package   Class		java-gnome
PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES    All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD