## XLib Surfaces

XLib Surfaces — X Window System rendering using XLib

## Synopsis

    #define             CAIRO_HAS_XLIB_SURFACE
    cairo_surface_t *   cairo_xlib_surface_create           (Display *dpy,
                                                             Drawable drawable,
                                                             Visual *visual,
                                                             int width,
                                                             int height);
    cairo_surface_t *   cairo_xlib_surface_create_for_bitmap
                                                            (Display *dpy,
                                                             Pixmap bitmap,
                                                             Screen *screen,
                                                             int width,
                                                             int height);
    void                cairo_xlib_surface_set_size         (cairo_surface_t *surface,
                                                             int width,
                                                             int height);
    Display *           cairo_xlib_surface_get_display      (cairo_surface_t *surface);
    Screen *            cairo_xlib_surface_get_screen       (cairo_surface_t *surface);
    void                cairo_xlib_surface_set_drawable     (cairo_surface_t *surface,
                                                             Drawable drawable,
                                                             int width,
                                                             int height);
    Drawable            cairo_xlib_surface_get_drawable     (cairo_surface_t *surface);
    Visual *            cairo_xlib_surface_get_visual       (cairo_surface_t *surface);
    int                 cairo_xlib_surface_get_width        (cairo_surface_t *surface);
    int                 cairo_xlib_surface_get_height       (cairo_surface_t *surface);
    int                 cairo_xlib_surface_get_depth        (cairo_surface_t *surface);

## Description

The XLib surface is used to render cairo graphics to X Window System windows and pixmaps using the XLib library.

Note that the XLib surface automatically takes advantage of X render extension if it is available.

## Details

### CAIRO_HAS_XLIB_SURFACE

    #define CAIRO_HAS_XLIB_SURFACE 1

Defined if the Xlib surface backend is available. This macro can be used to conditionally compile backend-specific code.

### cairo_xlib_surface_create ()

    cairo_surface_t *   cairo_xlib_surface_create           (Display *dpy,
                                                             Drawable drawable,
                                                             Visual *visual,
                                                             int width,
                                                             int height);

Creates an Xlib surface that draws to the given drawable. The way that colors are represented in the drawable is specified by the provided visual.

Note: If `drawable` is a Window, then the function `cairo_xlib_surface_set_size()` must be called whenever the size of the window changes.

When `drawable` is a Window containing child windows then drawing to the created surface will be clipped by those child windows. When the created surface is used as a source, the contents of the children will be included.

`dpy` : | an X Display
`drawable` : | an X Drawable, (a Pixmap or a Window)
`visual` : | the visual to use for drawing to `drawable`. The depth of the visual must match the depth of the drawable. Currently, only TrueColor visuals are fully supported.
`width` : | the current width of `drawable`.
`height` : | the current height of `drawable`.
Returns : | the newly created surface

### cairo_xlib_surface_create_for_bitmap ()

    cairo_surface_t *   cairo_xlib_surface_create_for_bitmap
                                                            (Display *dpy,
                                                             Pixmap bitmap,
                                                             Screen *screen,
                                                             int width,
                                                             int height);

Creates an Xlib surface that draws to the given bitmap. This will be drawn to as a `CAIRO_FORMAT_A1` object.

`dpy` : | an X Display
`bitmap` : | an X Drawable, (a depth-1 Pixmap)
`screen` : | the X Screen associated with `bitmap`
`width` : | the current width of `bitmap`.
`height` : | the current height of `bitmap`.
Returns : | the newly created surface

### cairo_xlib_surface_set_size ()

    void                cairo_xlib_surface_set_size         (cairo_surface_t *surface,
                                                             int width,
                                                             int height);

Informs cairo of the new size of the X Drawable underlying the surface. For a surface created for a Window (rather than a Pixmap), this function must be called each time the size of the window changes. (For a subwindow, you are normally resizing the window yourself, but for a toplevel window, it is necessary to listen for ConfigureNotify events.)

A Pixmap can never change size, so it is never necessary to call this function on a surface created for a Pixmap.

`surface` : | a cairo_surface_t for the XLib backend
`width` : | the new width of the surface
`height` : | the new height of the surface

### cairo_xlib_surface_get_display ()

    Display *           cairo_xlib_surface_get_display      (cairo_surface_t *surface);

Get the X Display for the underlying X Drawable.

`surface` : | a cairo_xlib_surface_t
Returns : | the display.

Since 1.2

### cairo_xlib_surface_get_screen ()

    Screen *            cairo_xlib_surface_get_screen       (cairo_surface_t *surface);

Get the X Screen for the underlying X Drawable.

`surface` : | a cairo_xlib_surface_t
Returns : | the screen.

Since 1.2

### cairo_xlib_surface_set_drawable ()

    void                cairo_xlib_surface_set_drawable     (cairo_surface_t *surface,
                                                             Drawable drawable,
                                                             int width,
                                                             int height);

Informs cairo of a new X Drawable underlying the surface. The drawable must match the display, screen and format of the existing drawable or the application will get X protocol errors and will probably terminate. No checks are done by this function to ensure this compatibility.

`surface` : | a cairo_surface_t for the XLib backend
`drawable` : | the new drawable for the surface
`width` : | the width of the new drawable
`height` : | the height of the new drawable

### cairo_xlib_surface_get_drawable ()

    Drawable            cairo_xlib_surface_get_drawable     (cairo_surface_t *surface);

Get the underlying X Drawable used for the surface.

`surface` : | a cairo_xlib_surface_t
Returns : | the drawable.

Since 1.2

### cairo_xlib_surface_get_visual ()

    Visual *            cairo_xlib_surface_get_visual       (cairo_surface_t *surface);

Gets the X Visual associated with `surface`, suitable for use with the underlying X Drawable. If `surface` was created by `cairo_xlib_surface_create()`, the return value is the Visual passed to that constructor.

`surface` : | a cairo_xlib_surface_t
Returns : | the Visual or `NULL` if there is no appropriate Visual for `surface`.

Since 1.2

### cairo_xlib_surface_get_width ()

    int                 cairo_xlib_surface_get_width        (cairo_surface_t *surface);

Get the width of the X Drawable underlying the surface in pixels.

`surface` : | a cairo_xlib_surface_t
Returns : | the width of the surface in pixels.

Since 1.2

### cairo_xlib_surface_get_height ()

    int                 cairo_xlib_surface_get_height       (cairo_surface_t *surface);

Get the height of the X Drawable underlying the surface in pixels.

`surface` : | a cairo_xlib_surface_t
Returns : | the height of the surface in pixels.

Since 1.2

### cairo_xlib_surface_get_depth ()

    int                 cairo_xlib_surface_get_depth        (cairo_surface_t *surface);

Get the number of bits used to represent each pixel value.

`surface` : | a cairo_xlib_surface_t
Returns : | the depth of the surface in bits.

Since 1.2

## See Also

cairo_surface_t