gfx/thebes/cairo-xlib-utils.h

   1 /* -*- Mode: C++; tab-width: 20; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  * This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifndef CAIROXLIBUTILS_H_
   7 #define CAIROXLIBUTILS_H_
   8
   9 #include "cairo.h"
  10 #include <X11/Xlib.h>
  11
  12 CAIRO_BEGIN_DECLS
  13
  14 /**
  15  * This callback encapsulates Xlib-based rendering. We assume that the
  16  * execution of the callback is equivalent to compositing some RGBA image of
  17  * size (bounds_width, bounds_height) onto the drawable at offset (offset_x,
  18  * offset_y), clipped to the union of the clip_rects if num_rects is greater
  19  * than zero. This includes the assumption that the same RGBA image
  20  * is composited if you call the callback multiple times with the same closure,
  21  * display and visual during a single cairo_draw_with_xlib call.
  22  *
  23  * @return True on success, False on non-recoverable error
  24  */
  25 typedef cairo_bool_t (*cairo_xlib_drawing_callback)(
  26     void* closure, Screen* screen, Drawable drawable, Visual* visual,
  27     short offset_x, short offset_y, XRectangle* clip_rects,
  28     unsigned int num_rects);
  29
  30 /**
  31  * This structure captures the result of the native drawing, in case the
  32  * caller may wish to reapply the drawing efficiently later.
  33  */
  34 typedef struct {
  35   cairo_surface_t* surface;
  36   cairo_bool_t uniform_alpha;
  37   cairo_bool_t uniform_color;
  38   double alpha;   /* valid only if uniform_alpha is TRUE */
  39   double r, g, b; /* valid only if uniform_color is TRUE */
  40 } cairo_xlib_drawing_result_t;
  41
  42 /**
  43  * This type specifies whether the native drawing callback draws all pixels
  44  * in its bounds opaquely, independent of the contents of the target drawable,
  45  * or whether it leaves pixels transparent/translucent or depends on the
  46  * existing contents of the target drawable in some way.
  47  */
  48 typedef enum _cairo_xlib_drawing_opacity {
  49   CAIRO_XLIB_DRAWING_OPAQUE,
  50   CAIRO_XLIB_DRAWING_TRANSPARENT
  51 } cairo_xlib_drawing_opacity_t;
  52
  53 /**
  54  * This type encodes the capabilities of the native drawing callback.
  55  *
  56  * If CAIRO_XLIB_DRAWING_SUPPORTS_OFFSET is set, 'offset_x' and 'offset_y'
  57  * can be nonzero in the call to the callback; otherwise they will be zero.
  58  *
  59  * If CAIRO_XLIB_DRAWING_SUPPORTS_CLIP_RECT is set, then 'num_rects' can be
  60  * zero or one in the call to the callback. If
  61  * CAIRO_XLIB_DRAWING_SUPPORTS_CLIP_LIST is set, then 'num_rects' can be
  62  * anything in the call to the callback. Otherwise 'num_rects' will be zero.
  63  * Do not set both of these values.
  64  *
  65  * If CAIRO_XLIB_DRAWING_SUPPORTS_ALTERNATE_SCREEN is set, then 'screen' can
  66  * be any screen on any display, otherwise it will be the default screen of
  67  * the display passed into cairo_draw_with_xlib.
  68  *
  69  * If CAIRO_XLIB_DRAWING_SUPPORTS_NONDEFAULT_VISUAL is set, then 'visual' can be
  70  * any visual, otherwise it will be equal to
  71  * DefaultVisualOfScreen (screen).
  72  */
  73 typedef enum {
  74   CAIRO_XLIB_DRAWING_SUPPORTS_OFFSET = 0x01,
  75   CAIRO_XLIB_DRAWING_SUPPORTS_CLIP_RECT = 0x02,
  76   CAIRO_XLIB_DRAWING_SUPPORTS_CLIP_LIST = 0x04,
  77   CAIRO_XLIB_DRAWING_SUPPORTS_ALTERNATE_SCREEN = 0x08,
  78   CAIRO_XLIB_DRAWING_SUPPORTS_NONDEFAULT_VISUAL = 0x10
  79 } cairo_xlib_drawing_support_t;
  80
  81 /**
  82  * Draw Xlib output into any cairo context. All cairo transforms and effects
  83  * are honored, including the current operator. This is equivalent to a
  84  * cairo_set_source_surface and then cairo_paint.
  85  * @param cr the context to draw into
  86  * @param callback the code to perform Xlib rendering
  87  * @param closure associated data
  88  * @param dpy an X display to use in case the cairo context has no associated X
  89  * display
  90  * @param width the width of the putative image drawn by the callback
  91  * @param height the height of the putative image drawn by the callback
  92  * @param is_opaque set to CAIRO_XLIB_DRAWING_IS_OPAQUE to indicate
  93  * that all alpha values of the putative image will be 1.0; the pixels drawn
  94  * into the Drawable must not depend on the prior contents of the Drawable in
  95  * any way
  96  * @param capabilities the capabilities of the callback as described above.
  97  * @param result if non-NULL, we *may* fill in the struct with information about
  98  * the rendered image. 'surface' may be filled in with a surface representing
  99  * the image, similar to the target of 'cr'. If 'uniform_alpha' is True then
 100  * every pixel of the image has the same alpha value 'alpha'. If
 101  * 'uniform_color' is True then every pixel of the image has the same RGB
 102  * color (r, g, b). If the image has uniform color and alpha (or alpha is zero,
 103  * in which case the color is always uniform) then we won't bother returning
 104  * a surface for it.
 105  */
 106 void cairo_draw_with_xlib(cairo_t* cr, cairo_xlib_drawing_callback callback,
 107                           void* closure, Display* dpy, unsigned int width,
 108                           unsigned int height,
 109                           cairo_xlib_drawing_opacity_t is_opaque,
 110                           cairo_xlib_drawing_support_t capabilities,
 111                           cairo_xlib_drawing_result_t* result);
 112
 113 CAIRO_END_DECLS
 114
 115 #endif /*CAIROXLIBUTILS_H_*/