/* Copyright (C) 2005 The cairomm Development Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
* 02110-1301, USA.
*/
#ifndef __CAIROMM_XLIB_SURFACE_H
#define __CAIROMM_XLIB_SURFACE_H
#include <cairomm/surface.h>
// This header is not included by cairomm.h because it requires X headers that
// tend to pollute the namespace with non-prefixed #defines and typedefs.
// You may include it directly if you need to use this API.
#ifdef CAIRO_HAS_XLIB_SURFACE
#include <cairo-xlib.h> // Needed for the X11 "Display" struct (which pollutes the namespace because it has no prefix.)
#ifdef CAIRO_HAS_XLIB_XRENDER_SURFACE
#include <cairo-xlib-xrender.h> // xrender-specific API
#endif // CAIRO_HAS_XLIB_XRENDER_SURFACE
#endif // CAIRO_HAS_XLIB_SURFACE
namespace Cairo
{
#ifdef CAIRO_HAS_XLIB_SURFACE
/** An XlibSurface provides a way to render to the X Window System using XLib.
* If you want to draw to the screen within an application that uses the X
* Window system, you should use this Surface type.
*
* @note For this surface to be availabe, cairo must have been compiled with
* support for XLib Surfaces
*/
class XlibSurface : public Surface
{
public:
/** Create a C++ wrapper for the C instance. This C++ instance should then be
* given to a RefPtr.
*
* @param cobject The C instance.
* @param has_reference whether we already have a reference. Otherwise, the
* constructor will take an extra reference.
*/
explicit XlibSurface(cairo_surface_t* cobject, bool has_reference = false);
virtual ~XlibSurface();
/** 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.
*
* @param dpy an X Display
* @param drawable an X Drawable, (a Pixmap or a Window)
* @param 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.
* @param width the current width of drawable.
* @param height the current height of drawable.
* @return A RefPtr to the newly created surface
*/
static RefPtr<XlibSurface> create(Display* dpy, Drawable drawable, Visual* visual, 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.
*
* @param dpy an X Display
* @param bitmap an X Drawable, (a depth-1 Pixmap)
* @param screen the X Screen associated with bitmap
* @param width the current width of bitmap.
* @param height the current height of bitmap.
* @return A RefPtr to the newly created surface
*/
static RefPtr<XlibSurface> create(Display *dpy, Pixmap bitmap, Screen *screen, 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.
*
* @param width the new width of the surface
* @param height the new height of the surface
*/
void set_size(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.
*
* @param drawable the new drawable for the surface
* @param width the width of the new drawable
* @param height the height of the new drawable
*/
void set_drawable(Drawable drawable, int width, int height);
/** gets the Drawable object associated with this surface */
Drawable get_drawable() const;
/** Get the X Display for the underlying X Drawable. */
const Display* get_display() const;
/** Get the X Display for the underlying X Drawable. */
Display* get_display();
/** Get the X Screen for the underlying X Drawable */
Screen* get_screen();
/** Get the X Screen for the underlying X Drawable */
const Screen* get_screen() const;
/** Get the X Visual for the underlying X Drawable */
Visual* get_visual();
/** Get the X Visual for the underlying X Drawable */
const Visual* get_visual() const;
/** Get the number of bits used to represent each pixel value. */
int get_depth() const;
/** Get the height in pixels of the X Drawable underlying the surface */
int get_height() const;
/** Get the width in pixels of the X Drawable underlying the surface */
int get_width() const;
#if CAIRO_HAS_XLIB_XRENDER_SURFACE
/**
* Creates an Xlib surface that draws to the given drawable. The way that
* colors are represented in the drawable is specified by the provided picture
* format.
*
* Note: If @drawable is a Window, then the function set_size() must be called
* whenever the size of the window changes.
*
* @param dpy an X Display
* @param drawable an X Drawable, (a Pixmap or a Window)
* @param screen the X Screen associated with @drawable
* @param format the picture format to use for drawing to @drawable. The depth
* of @format must match the depth of the drawable.
* @param width the current width of @drawable.
* @param height the current height of @drawable.
*
* @return the newly created surface
**/
static Cairo::RefPtr<Cairo::XlibSurface>
create_with_xrender_format (Display *dpy,
Drawable drawable,
Screen *screen,
XRenderPictFormat *format,
int width,
int height);
/**
* Gets the X Render picture format that @surface uses for rendering with the
* X Render extension. If the surface was created by
* cairo_xlib_surface_create_with_xrender_format() originally, the return
* value is the format passed to that constructor.
*
* Return value: the XRenderPictFormat* associated with @surface,
* or %NULL if the surface is not an xlib surface
* or if the X Render extension is not available.
*
* Since: 1.6
**/
XRenderPictFormat * get_xrender_format() const;
#endif // CAIRO_HAS_XLIB_XRENDER_SURFACE
};
#endif // CAIRO_HAS_XLIB_SURFACE
} // namespace Cairo
#endif //__CAIROMM_XLIB_SURFACE_H
// vim: ts=2 sw=2 et