/src/wrappers/cairo/library/cairo_surface.e
Specman e | 292 lines | 109 code | 47 blank | 136 comment | 3 complexity | 8bfb138e0fd513827bd8b664d5bca8cb MD5 | raw file
1note 2 description: "cairo_surface_t: base class for Cairo surfaces." 3 copyright: "[ 4 Copyright (C) 2007-2017: Paolo Redaelli, 5 Soluciones Informaticas Libres S.A. (Except), 6 Cairo team 7 8 This library is free software; you can redistribute it and/or 9 modify it under the terms of the GNU Lesser General Public License 10 as published by the Free Software Foundation; either version 2.1 of 11 the License, or (at your option) any later version. 12 13 This library is distributed in the hope that it will be useful, but 14 WITHOUT ANY WARRANTY; without even the implied warranty of 15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 Lesser General Public License for more details. 17 18 You should have received a copy of the GNU Lesser General Public 19 License along with this library; if not, write to the Free Software 20 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 21 02110-1301 USA 22 ]" 23 date: "$Date:$" 24 revision: "$Revision:$" 25 wrapped_version: "1.2.4" 26 27class CAIRO_SURFACE 28 -- A cairo_surface_t represents an image, either as the destination 29 -- of a drawing operation or as source when drawing onto another 30 -- surface. There are different subtypes of CAIRO_SURFACE for 31 -- different drawing backends; for example, CAIRO_IMAGE_SURFACE is 32 -- a bitmap image in memory. 33 34inherit 35 C_STRUCT 36 REFERENCE_COUNTED 37 38insert 39 CAIRO_SURFACE_EXTERNALS 40 CAIRO_SURFACE_TYPE 41 CAIRO_STATUS 42 CAIRO_CONTENT 43 44create {ANY} make_similar, from_external_pointer 45 46feature {ANY} -- Creation 47 48 make_similar (another: CAIRO_SURFACE; a_content: INTEGER; a_width, an_height: INTEGER) 49 -- Create a new surface that is as compatible as possible 50 -- with an existing surface. For example the new surface will 51 -- have the same fallback resolution and font options as 52 -- other. Generally, the new surface will also use the same 53 -- backend as other, unless that is not possible for some 54 -- reason. The type of the returned surface may be examined 55 -- with `type'. 56 57 -- Initially the surface contents are all 0 (transparent if 58 -- contents have transparency, black otherwise.) 59 60 -- `another': an existing surface used to select the backend 61 -- of the new surface 62 63 -- content : the content for the new surface 64 65 -- a_width: width of the new surface, (in device-space 66 -- units) 67 68 -- an_height : height of the new surface (in device-space units) 69 do 70 from_external_pointer(cairo_surface_create_similar 71 (another.handle, a_content, a_width, an_height)) 72 -- cairo_surface_create_similar returns a pointer to the 73 -- newly allocated surface. The caller owns the surface and 74 -- should call cairo_surface_destroy when done with it. This 75 -- function always returns a valid pointer, but it will 76 -- return a pointer to a "nil" surface if other is already in 77 -- an error state or any other error occurs. 78 end 79 80feature {ANY} -- Operations 81 82 finish 83 -- Finishes the surface and drops all references to external 84 -- resources. For example, for the Xlib backend it means that 85 -- cairo will no longer access the drawable, which can be 86 -- freed. After calling `finish' the only valid operations on 87 -- a surface are getting and setting user data and 88 -- referencing and destroying it. Further drawing to the 89 -- surface will not affect the surface but will instead 90 -- trigger a `cairo_status_surface_finished' error. 91 92 -- When the last call to `destroy' decreases the reference 93 -- count to zero, cairo will call `finish' if it hasn't been 94 -- called already, before freeing the resources associated 95 -- with the surface. 96 do 97 cairo_surface_finish(handle) 98 end 99 100 flush 101 -- Do any pending drawing for the surface and also restore 102 -- any temporary modification's cairo has made to the 103 -- surface's state. This function must be called before 104 -- switching from drawing on the surface with cairo to 105 -- drawing on it directly with native APIs. If the surface 106 -- doesn't support direct access, then this function does 107 -- nothing. 108 do 109 cairo_surface_flush(handle) 110 end 111 112 font_options: CAIRO_FONT_OPTIONS 113 -- the default font rendering options for the surface. This 114 -- allows display surfaces to report the correct subpixel 115 -- order for rendering on them, print surfaces to disable 116 -- hinting of metrics and so forth. The result can then be 117 -- used to create a CAIRO_SCALED_FONT. 118 do 119 create Result.make 120 cairo_surface_get_font_options (handle, Result.handle) 121 end 122 123 content: INTEGER 124 -- The content type of surface which indicates whether the 125 -- surface contains color and/or alpha information. See 126 -- CAIRO_CONTENT. 127 do 128 Result := cairo_surface_get_content (handle) 129 ensure 130 valid: is_valid_content (Result) 131 end 132 133 -- TODO: cairo_surface_set_user_data () 134 135 -- cairo_status_t cairo_surface_set_user_data (cairo_surface_t *surface, 136 -- const cairo_user_data_key_t *key, 137 -- void *user_data, 138 -- cairo_destroy_func_t destroy); 139 140 -- Attach user data to surface. To remove user data from a surface, call this 141 -- function with the key that was used to set it and NULL for data. 142 143 -- surface : a cairo_surface_t 144 -- key : the address of a cairo_user_data_key_t to attach the user data 145 -- to 146 -- user_data : the user data to attach to the surface 147 -- destroy : a cairo_destroy_func_t which will be called when the surface 148 -- is destroyed or when new user data is attached using the same 149 -- key. 150 -- Returns : CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY if a slot could 151 -- not be allocated for the user data. 152 153 -- -------------------------------------------------------------------------- 154 155 -- TODO: cairo_surface_get_user_data () 156 157 -- void* cairo_surface_get_user_data (cairo_surface_t *surface, 158 -- const cairo_user_data_key_t *key); 159 160 -- Return user data previously attached to surface using the specified key. 161 -- If no user data has been attached with the given key this function returns 162 -- NULL. 163 164 -- surface : a cairo_surface_t 165 -- key : the address of the cairo_user_data_key_t the user data was 166 -- attached to 167 -- Returns : the user data previously attached or NULL. 168 169 mark_dirty 170 -- Tells cairo that drawing has been done to surface using 171 -- means other than cairo, and that cairo should reread any 172 -- cached areas. Note that you must call `flush' before doing 173 -- such drawing. 174 do 175 cairo_surface_mark_dirty (handle) 176 end 177 178 mark_dirty_rectangle (an_x, an_y, a_width, an_height: INTEGER) 179 -- Like `mark_dirty', but drawing has been done only to the 180 -- specified rectangle, so that cairo can retain cached 181 -- contents for other parts of the surface. 182 183 -- Any cached clip set on the surface will be reset by this 184 -- function, to make sure that future cairo calls have the 185 -- clip set that they expect. 186 187 -- `an_x': X coordinate of dirty rectangle 188 -- `an_y': Y coordinate of dirty rectangle 189 -- `a_width': width of dirty rectangle 190 -- `an_height': height of dirty rectangle 191 do 192 cairo_surface_mark_dirty_rectangle (handle, an_x, an_y, a_width, an_height) 193 end 194 195 set_device_offset (an_offset: CAIRO_POINT) 196 -- Sets an offset that is added to the device coordinates 197 -- determined by the CTM when drawing to surface. One use 198 -- case for this function is when we want to create a 199 -- cairo_surface_t that redirects drawing for a portion of an 200 -- onscreen surface to an offscreen surface in a way that is 201 -- completely invisible to the user of the cairo API. Setting 202 -- a transformation via `translate' isn't sufficient to do 203 -- this, since functions like `device_to_user' will expose 204 -- the hidden offset. 205 206 -- Note that the offset affects drawing to the surface as 207 -- well as using the surface in a source pattern. 208 require 209 offset_not_void: an_offset /= Void 210 do 211 cairo_surface_set_device_offset (handle, an_offset.x, an_offset.y) 212 end 213 214 device_offset: CAIRO_POINT 215 -- the device offset as set by `set_device_offset'. 216 local 217 an_x, an_y: REAL 218 do 219 cairo_surface_get_device_offset (handle, $an_x, $an_y) 220 create Result.make(an_x,an_y) 221 end 222 223 set_fallback_resolution (x_pixels_per_inch, y_pixels_per_inch: REAL) 224 -- Set the horizontal and vertical resolution for image 225 -- fallbacks. 226 227 -- When certain operations aren't supported natively by a 228 -- backend, cairo will fallback by rendering operations to an 229 -- image and then overlaying that image onto the output. For 230 -- backends that are natively vector-oriented, this function 231 -- can be used to set the resolution used for these image 232 -- fallbacks, (larger values will result in more detailed 233 -- images, but also larger file sizes). 234 235 -- Some examples of natively vector-oriented backends are the 236 -- ps, pdf, and svg backends. 237 238 -- For backends that are natively raster-oriented, image 239 -- fallbacks are still possible, but they are always 240 -- performed at the native device resolution. So this 241 -- function has no effect on those backends. 242 243 -- NOTE: The fallback resolution only takes effect at the 244 -- time of completing a page (with `show_page' or 245 -- `copy_page') so there is currently no way to have more 246 -- than one fallback resolution in effect on a single page. 247 248 -- x_pixels_per_inch : horizontal setting for pixels per inch 249 -- y_pixels_per_inch : vertical setting for pixels per inch 250 do 251 cairo_surface_set_fallback_resolution (handle, x_pixels_per_inch, y_pixels_per_inch) 252 end 253 254 status: INTEGER 255 -- Checks whether an error has previously occurred for this surface. 256 do 257 Result := cairo_surface_status (handle) 258 ensure 259 valid_result: is_valid_cairo_status (Result) 260 end 261 262feature {ANY} -- Memory handling 263 ref 264 -- Increases the reference count on surface by one. This 265 -- prevents surface from being destroyed until a matching 266 -- call to `destroy' is made. 267 local 268 p: POINTER 269 do 270 p := cairo_surface_reference (handle) 271 check p=handle end 272 end 273 274 unref 275 -- Decreases the reference count on surface by one. If the 276 -- result is zero, then surface and all associated resources 277 -- are freed. See `reference'. 278 do 279 cairo_surface_destroy(handle) 280 end 281 282feature {WRAPPER, WRAPPER_HANDLER} -- Low-level features 283 type: INTEGER 284 -- the type of the backend used to create a surface. See 285 -- CAIRO_SURFACE_TYPE for available types. 286 do 287 Result := cairo_surface_get_type (handle) 288 ensure 289 is_valid_surface_type (Result) 290 end 291 292end -- class CAIRO_SURFACE