cairo-xlib-utils.h (5112B)
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_*/