1 /* 2 * This file is a part of the Cairo-Dock project 3 * 4 * Copyright : (C) see the 'copyright' file. 5 * E-mail : see the 'copyright' file. 6 * 7 * This program is free software; you can redistribute it and/or 8 * modify it under the terms of the GNU General Public License 9 * as published by the Free Software Foundation; either version 3 10 * of the License, or (at your option) any later version. 11 * 12 * This program is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 * GNU General Public License for more details. 16 * You should have received a copy of the GNU General Public License 17 * along with this program. If not, see <http://www.gnu.org/licenses/>. 18 */ 19 20 21 #ifndef __CAIRO_DOCK_SURFACE_FACTORY__ 22 #define __CAIRO_DOCK_SURFACE_FACTORY__ 23 24 #include <glib.h> 25 #include <gdk/gdk.h> 26 #include <cairo.h> 27 28 #include "cairo-dock-struct.h" 29 G_BEGIN_DECLS 30 31 /** 32 *@file cairo-dock-surface-factory.h This class contains functions to load any image/X buffer/GdkPixbuf/text into a cairo-surface. 33 * The loading of an image can be modified by a mask, to take into account the ratio, zoom, orientation, etc. 34 * 35 * The general way to load an image is by using \ref cairo_dock_create_surface_from_image. 36 * 37 * If you just want to load an image at a given size, use \ref cairo_dock_create_surface_from_image_simple, or \ref cairo_dock_create_surface_from_icon. 38 * 39 * To load a text into a surface, describe your text look with a _GldiTextDescription, and pass it to \ref cairo_dock_create_surface_from_text. 40 * 41 * Note: if you also need to load the image into a texture, it's easier to use the higher level ImageBuffer API (see \ref cairo_dock_create_image_buffer). 42 */ 43 44 /// Types of image loading modifiers. 45 typedef enum { 46 /// fill the space, with transparency if necessary. 47 CAIRO_DOCK_FILL_SPACE = 1<<0, 48 /// keep the ratio of the original image. 49 CAIRO_DOCK_KEEP_RATIO = 1<<1, 50 /// don't zoom in the image if the final surface is larger than the original image. 51 CAIRO_DOCK_DONT_ZOOM_IN = 1<<2, 52 /// orientation horizontal flip 53 CAIRO_DOCK_ORIENTATION_HFLIP = 1<<3, 54 /// orientation 180° rotation 55 CAIRO_DOCK_ORIENTATION_ROT_180 = 2<<3, 56 /// orientation vertical flip 57 CAIRO_DOCK_ORIENTATION_VFLIP = 3<<3, 58 /// orientation 90° rotation + horizontal flip 59 CAIRO_DOCK_ORIENTATION_ROT_90_HFLIP = 4<<3, 60 /// orientation 90° rotation 61 CAIRO_DOCK_ORIENTATION_ROT_90 = 5<<3, 62 /// orientation 90° rotation + vertical flip 63 CAIRO_DOCK_ORIENTATION_ROT_90_VFLIP = 6<<3, 64 /// orientation 270° rotation 65 CAIRO_DOCK_ORIENTATION_ROT_270 = 7<<3, 66 /// load the image as a strip if possible. 67 CAIRO_DOCK_ANIMATED_IMAGE = 1<<6 68 } CairoDockLoadImageModifier; 69 /// mask to get the orientation from a CairoDockLoadImageModifier. 70 #define CAIRO_DOCK_ORIENTATION_MASK (7<<3) 71 72 73 /** Create a surface from raw data of an X icon. The biggest icon possible is taken. The ratio is kept, and the surface will fill the space with transparency if necessary. 74 *@param pXIconBuffer raw data of the icon. 75 *@param iBufferNbElements number of elements in the buffer. 76 *@param iWidth will be filled with the resulting width of the surface. 77 *@param iHeight will be filled with the resulting height of the surface. 78 *@return the newly allocated surface. 79 */ 80 cairo_surface_t *cairo_dock_create_surface_from_xicon_buffer (gulong *pXIconBuffer, int iBufferNbElements, int iWidth, int iHeight); 81 82 /** Create a surface from a GdkPixbuf. 83 *@param pixbuf the pixbuf. 84 *@param fMaxScale maximum zoom of the icon. 85 *@param iWidthConstraint constraint on the width, or 0 to not constraint it. 86 *@param iHeightConstraint constraint on the height, or 0 to not constraint it. 87 *@param iLoadingModifier a mask of different loading modifiers. 88 *@param fImageWidth will be filled with the resulting width of the surface (hors zoom). 89 *@param fImageHeight will be filled with the resulting height of the surface (hors zoom). 90 *@param fZoomX if non NULL, will be filled with the zoom that has been applied on width. 91 *@param fZoomY if non NULL, will be filled with the zoom that has been applied on width. 92 *@return the newly allocated surface. 93 */ 94 cairo_surface_t *cairo_dock_create_surface_from_pixbuf (GdkPixbuf *pixbuf, double fMaxScale, int iWidthConstraint, int iHeightConstraint, CairoDockLoadImageModifier iLoadingModifier, double *fImageWidth, double *fImageHeight, double *fZoomX, double *fZoomY); 95 96 /** Create an empty surface (transparent) of a given size. In OpenGL mode, this surface can act as a buffer to generate a texture. 97 *@param iWidth width of the surface. 98 *@param iHeight height of the surface. 99 *@return the newly allocated surface. 100 */ 101 cairo_surface_t *cairo_dock_create_blank_surface (int iWidth, int iHeight); 102 103 /** Create a surface from any image. 104 *@param cImagePath complete path to the image. 105 *@param fMaxScale maximum zoom of the icon. 106 *@param iWidthConstraint constraint on the width, or 0 to not constraint it. 107 *@param iHeightConstraint constraint on the height, or 0 to not constraint it. 108 *@param iLoadingModifier a mask of different loading modifiers. 109 *@param fImageWidth will be filled with the resulting width of the surface (hors zoom). 110 *@param fImageHeight will be filled with the resulting height of the surface (hors zoom). 111 *@param fZoomX if non NULL, will be filled with the zoom that has been applied on width. 112 *@param fZoomY if non NULL, will be filled with the zoom that has been applied on width. 113 *@return the newly allocated surface. 114 */ 115 cairo_surface_t *cairo_dock_create_surface_from_image (const gchar *cImagePath, double fMaxScale, int iWidthConstraint, int iHeightConstraint, CairoDockLoadImageModifier iLoadingModifier, double *fImageWidth, double *fImageHeight, double *fZoomX, double *fZoomY); 116 117 /** Create a surface from any image, at a given size. If the image is given by its sole name, it is searched inside the current theme root folder. 118 *@param cImageFile path or name of an image. 119 *@param fImageWidth the desired surface width. 120 *@param fImageHeight the desired surface height. 121 *@return the newly allocated surface. 122 */ 123 cairo_surface_t *cairo_dock_create_surface_from_image_simple (const gchar *cImageFile, double fImageWidth, double fImageHeight); 124 125 /** Create a surface from any image, at a given size. If the image is given by its sole name, it is searched inside the icons themes known by Cairo-Dock. 126 *@param cImagePath path or name of an image. 127 *@param fImageWidth the desired surface width. 128 *@param fImageHeight the desired surface height. 129 *@return the newly allocated surface. 130 */ 131 cairo_surface_t *cairo_dock_create_surface_from_icon (const gchar *cImagePath, double fImageWidth, double fImageHeight); 132 #define cairo_dock_create_surface_for_icon cairo_dock_create_surface_from_icon 133 134 /** Create a square surface from any image, at a given size. If the image is given by its sole name, it is searched inside the icons themes known by Cairo-Dock. 135 *@param cImagePath path or name of an image. 136 *@param fImageSize the desired surface size. 137 *@return the newly allocated surface. 138 */ 139 #define cairo_dock_create_surface_for_square_icon(cImagePath, fImageSize) cairo_dock_create_surface_for_icon (cImagePath, fImageSize, fImageSize) 140 141 /** Create a surface at a given size, and fill it with a pattern. If the pattern image is given by its sole name, it is searched inside the current theme root folder. 142 *@param cImageFile path or name of an image that will be repeated to fill the surface. 143 *@param fImageWidth the desired surface width. 144 *@param fImageHeight the desired surface height. 145 *@param fAlpha transparency of the pattern (1 means opaque). 146 *@return the newly allocated surface. 147 */ 148 cairo_surface_t *cairo_dock_create_surface_from_pattern (const gchar *cImageFile, double fImageWidth, double fImageHeight, double fAlpha); 149 150 /** Create a surface by rotating another. Only works for 1/4 of rounds. 151 *@param pSurface surface to rotate. 152 *@param fImageWidth the width of the surface. 153 *@param fImageHeight the height of the surface. 154 *@param fRotationAngle rotation angle to apply, in radians. 155 *@return the newly allocated surface. 156 */ 157 cairo_surface_t * cairo_dock_rotate_surface (cairo_surface_t *pSurface, double fImageWidth, double fImageHeight, double fRotationAngle); 158 159 /** Create a surface representing a text, according to a given text description. 160 *@param cText the text. 161 *@param pLabelDescription description of the text rendering. 162 *@param fMaxScale maximum zoom of the text. 163 *@param iMaxWidth maximum authorized width for the surface; it will be zoomed in to fits this limit. 0 for no limit. 164 *@param iTextWidth will be filled the width of the resulting surface. 165 *@param iTextHeight will be filled the height of the resulting surface. 166 *@return the newly allocated surface. 167 */ 168 cairo_surface_t *cairo_dock_create_surface_from_text_full (const gchar *cText, GldiTextDescription *pLabelDescription, double fMaxScale, int iMaxWidth, int *iTextWidth, int *iTextHeight); 169 170 /** Create a surface representing a text, according to a given text description. 171 *@param cText the text. 172 *@param pLabelDescription description of the text rendering. 173 *@param iTextWidthPtr will be filled the width of the resulting surface. 174 *@param iTextHeightPtr will be filled the height of the resulting surface. 175 *@return the newly allocated surface. 176 */ 177 #define cairo_dock_create_surface_from_text(cText, pLabelDescription, iTextWidthPtr, iTextHeightPtr) cairo_dock_create_surface_from_text_full (cText, pLabelDescription, 1., 0, iTextWidthPtr, iTextHeightPtr) 178 179 /** Create a surface identical to another, possibly resizing it. 180 *@param pSurface surface to duplicate. 181 *@param fWidth the width of the surface. 182 *@param fHeight the height of the surface. 183 *@param fDesiredWidth desired width of the copy (0 to keep the same size). 184 *@param fDesiredHeight desired height of the copy (0 to keep the same size). 185 *@return the newly allocated surface. 186 */ 187 cairo_surface_t * cairo_dock_duplicate_surface (cairo_surface_t *pSurface, double fWidth, double fHeight, double fDesiredWidth, double fDesiredHeight); 188 189 190 G_END_DECLS 191 #endif 192