1 /* This file is part of GEGL. 2 * 3 * This library is free software; you can redistribute it and/or 4 * modify it under the terms of the GNU Lesser General Public 5 * License as published by the Free Software Foundation; either 6 * version 3 of the License, or (at your option) any later version. 7 * 8 * This library is distributed in the hope that it will be useful, 9 * but WITHOUT ANY WARRANTY; without even the implied warranty of 10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 11 * Lesser General Public License for more details. 12 * 13 * You should have received a copy of the GNU Lesser General Public 14 * License along with this library; if not, see <https://www.gnu.org/licenses/>. 15 * 16 * Copyright 2006, 2007 Øyvind Kolås <pippin@gimp.org> 17 */ 18 19 #ifndef __GEGL_BUFFER_H__ 20 #define __GEGL_BUFFER_H__ 21 22 #include <glib-object.h> 23 #include <babl/babl.h> 24 #include "gegl-buffer-matrix2.h" 25 #include "gegl-buffer-enums.h" 26 27 #define GEGL_AUTO_ROWSTRIDE 0 28 29 G_BEGIN_DECLS 30 typedef struct _GeglTileBackend GeglTileBackend; 31 typedef struct _GeglBuffer GeglBuffer; 32 typedef struct _GeglSampler GeglSampler; 33 34 typedef struct _GeglRectangle GeglRectangle; 35 36 struct _GeglRectangle 37 { 38 gint x; 39 gint y; 40 gint width; 41 gint height; 42 }; 43 44 45 /*** 46 * GeglBuffer: 47 * 48 * GeglBuffer is the API used by GEGL for storing and retrieving raster data. 49 * GeglBuffer heavily relies on babl for translation and description of 50 * different pixel formats. 51 * 52 * Internally GeglBuffer currently uses a tiled mipmap pyramid structure that 53 * can be swapped to disk. In the future GeglBuffer might also support a linear 54 * backend, a GPU memory backend and a network backend for buffers. 55 */ 56 57 /** 58 * gegl_buffer_new: (skip) 59 * @extent: the geometry of the buffer (origin, width and height) a 60 * GeglRectangle. 61 * @format: the Babl pixel format to be used, create one with babl_format("RGBA 62 * u8") and similar. 63 * 64 * Create a new GeglBuffer of a given format with a given extent. It is 65 * possible to pass in NULL for both extent and format, a NULL extent creates 66 * an empty buffer and a NULL format makes the buffer default to "RGBA float". 67 */ 68 GeglBuffer * gegl_buffer_new (const GeglRectangle *extent, 69 const Babl *format); 70 71 /** 72 * gegl_buffer_new_for_backend: 73 * @extent: the geometry of the buffer (origin, width and height) a 74 * GeglRectangle. 75 * @backend: an instance of a GeglTileBackend subclass. 76 * 77 * Create a new GeglBuffer from a backend, if NULL is passed in the extent of 78 * the buffer will be inherited from the extent of the backend. 79 * 80 * returns a GeglBuffer, that holds a reference to the provided backend. 81 */ 82 GeglBuffer * gegl_buffer_new_for_backend (const GeglRectangle *extent, 83 GeglTileBackend *backend); 84 85 /** 86 * gegl_buffer_add_handler: 87 * @buffer: a #GeglBuffer 88 * @handler: a #GeglTileHandler 89 * 90 * Add a new tile handler in the existing chain of tile handler of a GeglBuffer. 91 */ 92 void gegl_buffer_add_handler (GeglBuffer *buffer, 93 gpointer handler); 94 95 /** 96 * gegl_buffer_remove_handler: 97 * @buffer: a #GeglBuffer 98 * @handler: a #GeglTileHandler 99 * 100 * Remove the provided tile handler in the existing chain of tile handler of a GeglBuffer. 101 */ 102 void gegl_buffer_remove_handler (GeglBuffer *buffer, 103 gpointer handler); 104 105 /** 106 * gegl_buffer_open: 107 * @path: the path to a gegl buffer on disk. 108 * 109 * Open an existing on-disk GeglBuffer, this buffer is opened in a monitored 110 * state so multiple instances of gegl can share the same buffer. Sets on 111 * one buffer are reflected in the other. 112 * 113 * Returns: (transfer full): a GeglBuffer object. 114 */ 115 GeglBuffer * gegl_buffer_open (const gchar *path); 116 117 /** 118 * gegl_buffer_save: 119 * @buffer: (transfer none): a #GeglBuffer. 120 * @path: the path where the gegl buffer will be saved, any writable GIO uri is valid. 121 * @roi: the region of interest to write, this is the tiles that will be collected and 122 * written to disk. 123 * 124 * Write a GeglBuffer to a file. 125 */ 126 void gegl_buffer_save (GeglBuffer *buffer, 127 const gchar *path, 128 const GeglRectangle *roi); 129 130 /** 131 * gegl_buffer_load: 132 * @path: the path to a gegl buffer on disk. 133 * 134 * Loads an existing GeglBuffer from disk, if it has previously been saved with 135 * gegl_buffer_save it should be possible to open through any GIO transport, buffers 136 * that have been used as swap needs random access to be opened. 137 * 138 * Returns: (transfer full): a #GeglBuffer object. 139 */ 140 GeglBuffer * gegl_buffer_load (const gchar *path); 141 142 /** 143 * gegl_buffer_flush: 144 * @buffer: a #GeglBuffer 145 * 146 * Flushes all unsaved data to disk, this is not necessary for shared 147 * geglbuffers opened with gegl_buffer_open since they auto-sync on writes. 148 */ 149 void gegl_buffer_flush (GeglBuffer *buffer); 150 151 152 /** 153 * gegl_buffer_create_sub_buffer: 154 * @buffer: (transfer none): parent buffer. 155 * @extent: (transfer none): coordinates of new buffer. 156 * 157 * Create a new sub GeglBuffer, that is a view on a larger buffer. 158 * 159 * Return value: (transfer full): the new sub buffer 160 */ 161 GeglBuffer * gegl_buffer_create_sub_buffer (GeglBuffer *buffer, 162 const GeglRectangle *extent); 163 164 /** 165 * gegl_buffer_get_extent: 166 * @buffer: the buffer to operate on. 167 * 168 * Returns a pointer to a GeglRectangle structure defining the geometry of a 169 * specific GeglBuffer, this is also the default width/height of buffers passed 170 * in to gegl_buffer_set and gegl_buffer_get (with a scale of 1.0 at least). 171 */ 172 const GeglRectangle * gegl_buffer_get_extent (GeglBuffer *buffer); 173 174 175 /** 176 * gegl_buffer_set_extent: 177 * @buffer: the buffer to operate on. 178 * @extent: new extent. 179 * 180 * Changes the size and position that is considered active in a buffer, this 181 * operation is valid on any buffer, reads on subbuffers outside the master 182 * buffer's extent are at the moment undefined. 183 * 184 * Returns TRUE if the change of extent was successful. 185 */ 186 gboolean gegl_buffer_set_extent (GeglBuffer *buffer, 187 const GeglRectangle *extent); 188 189 /** 190 * gegl_buffer_set_abyss: 191 * @buffer: the buffer to operate on. 192 * @abyss: new abyss. 193 * 194 * Changes the size and position of the abyss rectangle of a buffer. 195 * 196 * Returns TRUE if the change of abyss was successful. 197 */ 198 gboolean gegl_buffer_set_abyss (GeglBuffer *buffer, 199 const GeglRectangle *abyss); 200 201 /* convenience access macros */ 202 203 /** 204 * gegl_buffer_get_x: 205 * @buffer: a GeglBuffer 206 * 207 * Evaluates to the X coordinate of the upper left corner of the buffer's extent. 208 */ 209 #define gegl_buffer_get_x(buffer) (gegl_buffer_get_extent(buffer)->x) 210 211 /** 212 * gegl_buffer_get_y: 213 * @buffer: a GeglBuffer 214 * 215 * Evaluates to the Y coordinate of the upper left corner of the buffer's extent. 216 */ 217 #define gegl_buffer_get_y(buffer) (gegl_buffer_get_extent(buffer)->y) 218 219 /** 220 * gegl_buffer_get_width: 221 * @buffer: a GeglBuffer 222 * 223 * Evaluates to the width of the buffer's extent. 224 */ 225 #define gegl_buffer_get_width(buffer) (gegl_buffer_get_extent(buffer)->width) 226 227 /** 228 * gegl_buffer_get_height: 229 * @buffer: a GeglBuffer 230 * 231 * Evaluates to the height of the buffer's extent. 232 */ 233 #define gegl_buffer_get_height(buffer) (gegl_buffer_get_extent(buffer)->height) 234 235 /** 236 * gegl_buffer_get_pixel_count: 237 * @buffer: a GeglBuffer 238 * 239 * Returns the number of pixels of the extent of the buffer. 240 */ 241 #define gegl_buffer_get_pixel_count(buffer) (gegl_buffer_get_width(buffer) * gegl_buffer_get_height(buffer)) 242 243 /** 244 * gegl_buffer_get: (skip) 245 * @buffer: the buffer to retrieve data from. 246 * @rect: the coordinates we want to retrieve data from, and width/height of 247 * destination buffer, if NULL equal to the extent of the buffer. The 248 * coordinates and dimensions are after scale has been applied. 249 * @scale: sampling scale, 1.0 = pixel for pixel 2.0 = magnify, 0.5 scale down. 250 * @format: the BablFormat to store in the linear buffer @dest. 251 * @dest: the memory destination for a linear buffer for the pixels, the size needed 252 * depends on the requested BablFormat. 253 * @rowstride: rowstride in bytes, or GEGL_AUTO_ROWSTRIDE to compute the 254 * rowstride based on the width and bytes per pixel for the specified format. 255 * @repeat_mode: how requests outside the buffer extent are handled. 256 * Valid values: GEGL_ABYSS_NONE (abyss pixels are zeroed), GEGL_ABYSS_WHITE 257 * (abyss pixels are white), GEGL_ABYSS_BLACK (abyss pixels are black), 258 * GEGL_ABYSS_CLAMP (coordinates are clamped to the abyss rectangle), 259 * GEGL_ABYSS_LOOP (buffer contents are tiled if outside of the abyss rectangle) 260 * this argument also takes a GEGL_BUFFER_FILTER value or'ed into it, allowing 261 * to specify trade-off of performance/quality, valid values are: 262 * GEGL_BUFFER_FILTER_NEAREST, GEGL_BUFFER_FILTER_BILINEAR, 263 * GEGL_BUFFER_FILTER_BOX and GEGL_BUFFER_FILTER_AUTO. 264 * 265 * Fetch a rectangular linear buffer of pixel data from the GeglBuffer, the 266 * data is converted to the desired BablFormat, if the BablFormat stored and 267 * fetched is the same this amounts to a series of memcpy's aligned to demux 268 * the tile structure into a linear buffer. 269 * 270 */ 271 void gegl_buffer_get (GeglBuffer *buffer, 272 const GeglRectangle *rect, 273 gdouble scale, 274 const Babl *format, 275 gpointer dest, 276 gint rowstride, 277 GeglAbyssPolicy repeat_mode); 278 279 /** 280 * gegl_buffer_set: (skip) 281 * @buffer: the buffer to modify. 282 * @rect: the coordinates we want to change the data of and the width/height of 283 * the linear buffer being set. 284 * the data when setting. 285 * @mipmap_level: the scale level being set, 0 = 1:1 = default = base mipmap level, 286 * 1 = 1:2, 2=1:4, 3=1:8 .. 287 * @format: the babl_format the linear buffer @src. 288 * @src: linear buffer of image data to be stored in @buffer. 289 * @rowstride: rowstride in bytes, or GEGL_AUTO_ROWSTRIDE to compute the 290 * rowstride based on the width and bytes per pixel for the specified format. 291 * 292 * Store a linear raster buffer into the GeglBuffer. 293 */ 294 void gegl_buffer_set (GeglBuffer *buffer, 295 const GeglRectangle *rect, 296 gint mipmap_level, 297 const Babl *format, 298 const void *src, 299 gint rowstride); 300 301 302 303 /** 304 * gegl_buffer_set_color_from_pixel: 305 * @buffer: a #GeglBuffer 306 * @rect: a rectangular region to fill with a color. 307 * @pixel: pointer to the data of a single pixel 308 * @pixel_format: the babl format of the pixel, if missing - the soft format of dst. 309 * 310 * Sets the region covered by rect to the the provided pixel. 311 */ 312 void 313 gegl_buffer_set_color_from_pixel (GeglBuffer *buffer, 314 const GeglRectangle *rect, 315 gconstpointer pixel, 316 const Babl *pixel_format); 317 318 319 /** 320 * gegl_buffer_set_pattern: 321 * @buffer: a #GeglBuffer 322 * @rect: the region of @buffer to fill 323 * @pattern: a #GeglBuffer to be repeated as a pattern 324 * @x_offset: where the pattern starts horizontally 325 * @y_offset: where the pattern starts vertical 326 * 327 * Fill a region with a repeating pattern. Offsets parameters are 328 * relative to the origin (0, 0) and not to the rectangle. So be carefull 329 * about the origin of @pattern and @buffer extents. 330 */ 331 void gegl_buffer_set_pattern (GeglBuffer *buffer, 332 const GeglRectangle *rect, 333 GeglBuffer *pattern, 334 gint x_offset, 335 gint y_offset); 336 337 /** 338 * gegl_buffer_get_format: (skip) 339 * @buffer: a #GeglBuffer 340 * 341 * Get the babl format of the buffer, this might not be the format the buffer 342 * was originally created with, you need to use gegl_buffer_set_format (buf, 343 * NULL); to retrieve the original format (potentially having saved away the 344 * original format of the buffer to re-set it.) 345 * 346 * Returns: the babl format used for storing pixels in the buffer. 347 * 348 */ 349 const Babl * gegl_buffer_get_format (GeglBuffer *buffer); 350 351 352 /** 353 * gegl_buffer_set_format: (skip) 354 * @buffer: a #GeglBuffer 355 * @format: the new babl format, must have same bpp as original format. 356 * 357 * Set the babl format of the buffer, setting the babl format of the buffer 358 * requires the new format to have exactly the same bytes per pixel as the 359 * original format. If NULL is passed in the format of the buffer is reset to 360 * the original format. 361 * 362 * Returns: the new babl format or NULL if the passed-in buffer was 363 * incompatible (then the original format is still used). 364 */ 365 const Babl * gegl_buffer_set_format (GeglBuffer *buffer, 366 const Babl *format); 367 368 /** 369 * gegl_buffer_clear: 370 * @buffer: a #GeglBuffer 371 * @roi: a rectangular region 372 * 373 * Clears the provided rectangular region by setting all the associated memory 374 * to 0. 375 */ 376 void gegl_buffer_clear (GeglBuffer *buffer, 377 const GeglRectangle *roi); 378 379 380 /** 381 * gegl_buffer_copy: 382 * @src: (transfer none): source buffer. 383 * @src_rect: source rectangle (or NULL to copy entire source buffer) 384 * @repeat_mode: the abyss policy to be using if src_rect is outside src's extent. 385 * @dst: (transfer none): destination buffer. 386 * @dst_rect: position of upper left destination pixel (or NULL to match @src_rect) 387 * 388 * Copy a region from source buffer to destination buffer. 389 * 390 * If the babl_formats of the buffers are the same, and the tile boundaries 391 * align, this will create copy-on-write tiles in the destination buffer. 392 * 393 * This function never does any scaling. When src_rect and dst_rect do not have 394 * the same width and height, the size of src_rect is used. 395 */ 396 void gegl_buffer_copy (GeglBuffer *src, 397 const GeglRectangle *src_rect, 398 GeglAbyssPolicy repeat_mode, 399 GeglBuffer *dst, 400 const GeglRectangle *dst_rect); 401 402 403 404 /** 405 * gegl_buffer_dup: 406 * @buffer: (transfer none): the GeglBuffer to duplicate. 407 * 408 * Duplicate a buffer (internally uses gegl_buffer_copy). Aligned tiles 409 * will create copy-on-write clones in the new buffer. 410 * 411 * Return value: (transfer full): the new buffer 412 */ 413 GeglBuffer * gegl_buffer_dup (GeglBuffer *buffer); 414 415 416 /** 417 * gegl_buffer_sample_at_level: (skip) 418 * @buffer: the GeglBuffer to sample from 419 * @x: x coordinate to sample in buffer coordinates 420 * @y: y coordinate to sample in buffer coordinates 421 * @scale: a matrix that indicates scaling factors, see 422 * gegl_sampler_compute_scale the same. 423 * @dest: buffer capable of storing one pixel in @format. 424 * @format: the format to store the sampled color in. 425 * @level: mipmap level to sample from (@x and @y are level 0 coordinates) 426 * @sampler_type: the sampler type to use, 427 * to be ported from working code. Valid values: GEGL_SAMPLER_NEAREST, 428 * GEGL_SAMPLER_LINEAR, GEGL_SAMPLER_CUBIC, GEGL_SAMPLER_NOHALO and 429 * GEGL_SAMPLER_LOHALO 430 * @repeat_mode: how requests outside the buffer extent are handled. 431 * Valid values: GEGL_ABYSS_NONE (abyss pixels are zeroed), GEGL_ABYSS_WHITE 432 * (abyss pixels are white), GEGL_ABYSS_BLACK (abyss pixels are black), 433 * GEGL_ABYSS_CLAMP (coordinates are clamped to the abyss rectangle), 434 * GEGL_ABYSS_LOOP (buffer contents are tiled if outside of the abyss rectangle). 435 * 436 * Query interpolate pixel values at a given coordinate using a specified form 437 * of interpolation. 438 * 439 * If you intend to take multiple samples, consider using 440 * gegl_buffer_sampler_new_at_level() to create a sampler object instead, which 441 * is more efficient. 442 */ 443 444 void gegl_buffer_sample_at_level (GeglBuffer *buffer, 445 gdouble x, 446 gdouble y, 447 GeglBufferMatrix2 *scale, 448 gpointer dest, 449 const Babl *format, 450 gint level, 451 GeglSamplerType sampler_type, 452 GeglAbyssPolicy repeat_mode); 453 454 /** 455 * gegl_buffer_sample: (skip) 456 * @buffer: the GeglBuffer to sample from 457 * @x: x coordinate to sample in buffer coordinates 458 * @y: y coordinate to sample in buffer coordinates 459 * @scale: a matrix that indicates scaling factors, see 460 * gegl_sampler_compute_scale the same. 461 * @dest: buffer capable of storing one pixel in @format. 462 * @format: the format to store the sampled color in. 463 * @sampler_type: the sampler type to use, 464 * to be ported from working code. Valid values: GEGL_SAMPLER_NEAREST, 465 * GEGL_SAMPLER_LINEAR, GEGL_SAMPLER_CUBIC, GEGL_SAMPLER_NOHALO and 466 * GEGL_SAMPLER_LOHALO 467 * @repeat_mode: how requests outside the buffer extent are handled. 468 * Valid values: GEGL_ABYSS_NONE (abyss pixels are zeroed), GEGL_ABYSS_WHITE 469 * (abyss pixels are white), GEGL_ABYSS_BLACK (abyss pixels are black), 470 * GEGL_ABYSS_CLAMP (coordinates are clamped to the abyss rectangle), 471 * GEGL_ABYSS_LOOP (buffer contents are tiled if outside of the abyss rectangle). 472 * 473 * Query interpolate pixel values at a given coordinate using a specified form 474 * of interpolation. 475 * 476 * If you intend to take multiple samples, consider using 477 * gegl_buffer_sampler_new() to create a sampler object instead, which is more 478 * efficient. 479 */ 480 void gegl_buffer_sample (GeglBuffer *buffer, 481 gdouble x, 482 gdouble y, 483 GeglBufferMatrix2 *scale, 484 gpointer dest, 485 const Babl *format, 486 GeglSamplerType sampler_type, 487 GeglAbyssPolicy repeat_mode); 488 489 490 491 /** 492 * gegl_buffer_sample_cleanup: 493 * @buffer: the GeglBuffer to sample from 494 * 495 * Clean up resources used by sampling framework of buffer. 496 * 497 * Deprecated: 0.4.2: This function has no effect. It is not necessary to call 498 * it after using gegl_buffer_sample() or gegl_buffer_sample_at_level(). 499 */ 500 G_DEPRECATED 501 void gegl_buffer_sample_cleanup (GeglBuffer *buffer); 502 503 typedef void (*GeglSamplerGetFun) (GeglSampler *self, 504 gdouble x, 505 gdouble y, 506 GeglBufferMatrix2 *scale, 507 void *output, 508 GeglAbyssPolicy repeat_mode); 509 510 /** 511 * gegl_sampler_get_fun: (skip) 512 * 513 * Get the raw sampler function, the raw sampler function does not do 514 * additional NaN / inifinity checks on passed in coordinates. 515 */ 516 GeglSamplerGetFun gegl_sampler_get_fun (GeglSampler *sampler); 517 518 519 /** 520 * gegl_buffer_sampler_new: (skip) 521 * @buffer: buffer to create a new sampler for 522 * @format: format we want data back in 523 * @sampler_type: the sampler type to use, 524 * to be ported from working code. Valid values: GEGL_SAMPLER_NEAREST, 525 * GEGL_SAMPLER_LINEAR, GEGL_SAMPLER_CUBIC, GEGL_SAMPLER_NOHALO and 526 * GEGL_SAMPLER_LOHALO 527 * 528 * Create a new sampler, when you are done with the sampler, g_object_unref 529 * it. 530 * 531 * Samplers only hold weak references to buffers, so if its buffer is freed 532 * the sampler will become invalid. 533 */ 534 GeglSampler * gegl_buffer_sampler_new (GeglBuffer *buffer, 535 const Babl *format, 536 GeglSamplerType sampler_type); 537 538 /** 539 * gegl_buffer_sampler_new_at_level: (skip) 540 * @buffer: buffer to create a new sampler for 541 * @format: format we want data back in 542 * @sampler_type: the sampler type to use, 543 * @level: the mipmap level to create a sampler for 544 * to be ported from working code. Valid values: GEGL_SAMPLER_NEAREST, 545 * GEGL_SAMPLER_LINEAR, GEGL_SAMPLER_CUBIC, GEGL_SAMPLER_NOHALO and 546 * GEGL_SAMPLER_LOHALO 547 * 548 * Create a new sampler, when you are done with the sampler, g_object_unref 549 * it. 550 * 551 * Samplers only hold weak references to buffers, so if its buffer is freed 552 * the sampler will become invalid. 553 */ 554 GeglSampler * gegl_buffer_sampler_new_at_level (GeglBuffer *buffer, 555 const Babl *format, 556 GeglSamplerType sampler_type, 557 gint level); 558 559 560 /** 561 * gegl_sampler_get: 562 * @sampler: a GeglSampler gotten from gegl_buffer_sampler_new 563 * @x: x coordinate to sample 564 * @y: y coordinate to sample 565 * @scale: matrix representing extent of sampling area in source buffer. 566 * @output: memory location for output data. 567 * @repeat_mode: how requests outside the buffer extent are handled. 568 * Valid values: GEGL_ABYSS_NONE (abyss pixels are zeroed), GEGL_ABYSS_WHITE 569 * (abyss pixels are white), GEGL_ABYSS_BLACK (abyss pixels are black), 570 * GEGL_ABYSS_CLAMP (coordinates are clamped to the abyss rectangle), 571 * GEGL_ABYSS_LOOP (buffer contents are tiled if outside of the abyss rectangle). 572 * 573 * Perform a sampling with the provided @sampler. 574 */ 575 void gegl_sampler_get (GeglSampler *sampler, 576 gdouble x, 577 gdouble y, 578 GeglBufferMatrix2 *scale, 579 void *output, 580 GeglAbyssPolicy repeat_mode); 581 582 /* code template utility, updates the jacobian matrix using 583 * a user defined mapping function for displacement, example 584 * with an identity transform (note that for the identity 585 * transform this is massive computational overhead that can 586 * be skipped by passing NULL to the sampler. 587 * 588 * #define gegl_unmap(x,y,dx,dy) { dx=x; dy=y; } 589 * 590 * gegl_sampler_compute_scale (scale, x, y); 591 * gegl_unmap(x,y,sample_x,sample_y); 592 * gegl_buffer_sample (buffer, sample_x, sample_y, scale, dest, format, 593 * GEGL_SAMPLER_LOHALO); 594 * 595 * #undef gegl_unmap // IMPORTANT undefine map macro 596 */ 597 #define gegl_sampler_compute_scale(matrix, x, y) \ 598 { \ 599 float ax, ay, bx, by; \ 600 gegl_unmap(x + 0.5, y, ax, ay); \ 601 gegl_unmap(x - 0.5, y, bx, by); \ 602 matrix.coeff[0][0] = ax - bx; \ 603 matrix.coeff[1][0] = ay - by; \ 604 gegl_unmap(x, y + 0.5, ax, ay); \ 605 gegl_unmap(x, y - 0.5, bx, by); \ 606 matrix.coeff[0][1] = ax - bx; \ 607 matrix.coeff[1][1] = ay - by; \ 608 } 609 610 611 /** 612 * gegl_sampler_get_context_rect: 613 * @sampler: a GeglSampler gotten from gegl_buffer_sampler_new 614 * 615 * Returns:The context rectangle of the given @sampler. 616 */ 617 const GeglRectangle * gegl_sampler_get_context_rect (GeglSampler *sampler); 618 619 /** 620 * gegl_buffer_linear_new: (skip) 621 * @extent: dimensions of buffer. 622 * @format: desired pixel format. 623 * 624 * Creates a GeglBuffer backed by a linear memory buffer, of the given 625 * @extent in the specified @format. babl_format ("R'G'B'A u8") for instance 626 * to make a normal 8bit buffer. 627 * 628 * Returns: a GeglBuffer that can be used as any other GeglBuffer. 629 */ 630 GeglBuffer * gegl_buffer_linear_new (const GeglRectangle *extent, 631 const Babl *format); 632 633 /** 634 * gegl_buffer_linear_new_from_data: (skip) 635 * @data: a pointer to a linear buffer in memory. 636 * @format: the format of the data in memory 637 * @extent: the dimensions (and upper left coordinates) of linear buffer. 638 * @rowstride: the number of bytes between rowstarts in memory (or 0 to 639 * autodetect) 640 * @destroy_fn: function to call to free data or NULL if memory should not be 641 * freed. 642 * @destroy_fn_data: extra argument to be passed to void destroy(ptr, data) type 643 * function. 644 * 645 * Creates a GeglBuffer backed by a linear memory buffer that already exists, 646 * of the given @extent in the specified @format. babl_format ("R'G'B'A u8") 647 * for instance to make a normal 8bit buffer. 648 * 649 * Returns: a GeglBuffer that can be used as any other GeglBuffer. 650 */ 651 GeglBuffer * gegl_buffer_linear_new_from_data (const gpointer data, 652 const Babl *format, 653 const GeglRectangle *extent, 654 gint rowstride, 655 GDestroyNotify destroy_fn, 656 gpointer destroy_fn_data); 657 658 /** 659 * gegl_buffer_linear_open: (skip) 660 * @buffer: a #GeglBuffer. 661 * @extent: region to open, pass NULL for entire buffer. 662 * @rowstride: return location for rowstride. 663 * @format: desired format or NULL to use buffers format. 664 * 665 * Raw direct random access to the full data of a buffer in linear memory. 666 * 667 * Returns: a pointer to a linear memory region describing the buffer, if the 668 * request is compatible with the underlying data storage direct access 669 * to the underlying data is provided. Otherwise, it returns a copy of the data. 670 */ 671 gpointer gegl_buffer_linear_open (GeglBuffer *buffer, 672 const GeglRectangle *extent, 673 gint *rowstride, 674 const Babl *format); 675 676 /** 677 * gegl_buffer_linear_close: 678 * @buffer: a #GeglBuffer. 679 * @linear: a previously returned buffer. 680 * 681 * This function makes sure GeglBuffer and underlying code is aware of changes 682 * being made to the linear buffer. If the request was not a compatible one 683 * it is written back to the buffer. Multiple concurrent users can be handed 684 * the same buffer (both raw access and converted). 685 */ 686 void gegl_buffer_linear_close (GeglBuffer *buffer, 687 gpointer linear); 688 689 690 /** 691 * gegl_buffer_get_abyss: 692 * @buffer: a #GeglBuffer. 693 * 694 * Return the abyss extent of a buffer, this expands out to the parents extent in 695 * subbuffers. 696 */ 697 const GeglRectangle * gegl_buffer_get_abyss (GeglBuffer *buffer); 698 699 700 /** 701 * gegl_buffer_share_storage: 702 * @buffer1: a #GeglBuffer. 703 * @buffer2: a #GeglBuffer. 704 * 705 * Checks if a pair of buffers share the same underlying tile storage. 706 * 707 * Returns TRUE if @buffer1 and @buffer2 share the same storage. 708 */ 709 gboolean gegl_buffer_share_storage (GeglBuffer *buffer1, 710 GeglBuffer *buffer2); 711 712 713 /** 714 * gegl_buffer_signal_connect: 715 * @buffer: a GeglBuffer 716 * @detailed_signal: only "changed" expected for now 717 * @c_handler: (scope async) : c function callback 718 * @data: user data: 719 * 720 * This function should be used instead of g_signal_connect when connecting to 721 * the GeglBuffer::changed signal handler, GeglBuffer contains additional 722 * machinery to avoid the overhead of changes when no signal handler have been 723 * connected, if regular g_signal_connect is used; then no signals will be 724 * emitted. 725 * 726 * Returns: an handle like g_signal_connect. 727 */ 728 glong gegl_buffer_signal_connect (GeglBuffer *buffer, 729 const char *detailed_signal, 730 GCallback c_handler, 731 gpointer data); 732 733 /** 734 * gegl_buffer_freeze_changed: 735 * @buffer: a GeglBuffer 736 * 737 * Blocks emission of the "changed" signal for @buffer. 738 * 739 * While the signal is blocked, changes to @buffer are accumulated, and will 740 * be emitted once the signal is unblocked, using gegl_buffer_thaw_changed(). 741 */ 742 void gegl_buffer_freeze_changed (GeglBuffer *buffer); 743 744 /** 745 * gegl_buffer_thaw_changed: 746 * @buffer: a GeglBuffer 747 * 748 * Unblocks emission of the "changed" signal for @buffer. 749 * 750 * Once all calls to gegl_buffer_freeze_changed() are matched by corresponding 751 * calls to gegl_buffer_freeze_changed(), all accumulated changes are emitted. 752 */ 753 void gegl_buffer_thaw_changed (GeglBuffer *buffer); 754 755 756 /** 757 * gegl_buffer_flush_ext: 758 * @buffer: a GeglBuffer 759 * @rect: rectangle 760 * 761 * Invokes the external flush function, if any is set on the provided buffer - 762 * this ensures that data pending - in the current implementation only OpenCL - 763 * externally to be synchronized with the buffer. Multi threaded code should 764 * call such a synchronization before branching out to avoid each of the 765 * threads having an implicit synchronization of its own. 766 */ 767 void 768 gegl_buffer_flush_ext (GeglBuffer *buffer, const GeglRectangle *rect); 769 770 #include "gegl-buffer-iterator.h" 771 #include "gegl-rectangle.h" 772 #include "gegl-memory.h" 773 #include "gegl-scratch.h" 774 775 776 GType gegl_buffer_get_type (void) G_GNUC_CONST; 777 #define GEGL_TYPE_BUFFER (gegl_buffer_get_type ()) 778 #define GEGL_BUFFER(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GEGL_TYPE_BUFFER, GeglBuffer)) 779 #define GEGL_IS_BUFFER(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GEGL_TYPE_BUFFER)) 780 G_DEFINE_AUTOPTR_CLEANUP_FUNC (GeglBuffer, g_object_unref) 781 782 783 G_END_DECLS 784 #endif 785