/* 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