gimpdrawable_pdb.c 29.3 KB
Newer Older
1
/* LIBGIMP - The GIMP Library
2
 * Copyright (C) 1995-2003 Peter Mattis and Spencer Kimball
3 4
 *
 * gimpdrawable_pdb.c
Manish Singh's avatar
Manish Singh committed
5
 *
6
 * This library is free software: you can redistribute it and/or
Marc Lehmann's avatar
Marc Lehmann committed
7
 * modify it under the terms of the GNU Lesser General Public
Manish Singh's avatar
Manish Singh committed
8
 * License as published by the Free Software Foundation; either
9
 * version 3 of the License, or (at your option) any later version.
10 11 12 13
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14
 * Lesser General Public License for more details.
Manish Singh's avatar
Manish Singh committed
15
 *
Marc Lehmann's avatar
Marc Lehmann committed
16
 * You should have received a copy of the GNU Lesser General Public
17
 * License along with this library.  If not, see
18
 * <https://www.gnu.org/licenses/>.
19 20
 */

21
/* NOTE: This file is auto-generated by pdbgen.pl */
22

Sven Neumann's avatar
Sven Neumann committed
23 24
#include "config.h"

25 26
#include <string.h>

Elliot Lee's avatar
Elliot Lee committed
27 28
#include "gimp.h"

29 30 31 32 33 34 35 36 37 38

/**
 * SECTION: gimpdrawable
 * @title: gimpdrawable
 * @short_description: Functions to manipulate drawables.
 *
 * Functions to manipulate drawables.
 **/


39 40 41 42 43 44 45 46 47 48
/**
 * _gimp_drawable_get_format:
 * @drawable_ID: The drawable.
 *
 * Returns the drawable's Babl format
 *
 * This procedure returns the drawable's Babl format.
 *
 * Returns: The drawable's Babl format.
 *
49
 * Since: 2.10
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70
 **/
gchar *
_gimp_drawable_get_format (gint32 drawable_ID)
{
  GimpParam *return_vals;
  gint nreturn_vals;
  gchar *format = NULL;

  return_vals = gimp_run_procedure ("gimp-drawable-get-format",
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_END);

  if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
    format = g_strdup (return_vals[1].data.d_string);

  gimp_destroy_params (return_vals, nreturn_vals);

  return format;
}

71
/**
72
 * gimp_drawable_type:
73 74
 * @drawable_ID: The drawable.
 *
75
 * Returns the drawable's type.
76
 *
77
 * This procedure returns the drawable's type.
78
 *
79
 * Returns: The drawable's type.
80
 **/
81 82
GimpImageType
gimp_drawable_type (gint32 drawable_ID)
Elliot Lee's avatar
Elliot Lee committed
83
{
84
  GimpParam *return_vals;
85
  gint nreturn_vals;
86
  GimpImageType type = 0;
Elliot Lee's avatar
Elliot Lee committed
87

88
  return_vals = gimp_run_procedure ("gimp-drawable-type",
89 90 91
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_END);
Elliot Lee's avatar
Elliot Lee committed
92

93
  if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
94
    type = return_vals[1].data.d_int32;
Elliot Lee's avatar
Elliot Lee committed
95 96 97

  gimp_destroy_params (return_vals, nreturn_vals);

98
  return type;
Elliot Lee's avatar
Elliot Lee committed
99 100
}

101
/**
102
 * gimp_drawable_type_with_alpha:
103 104
 * @drawable_ID: The drawable.
 *
105
 * Returns the drawable's type with alpha.
106
 *
107 108
 * This procedure returns the drawable's type as if had an alpha
 * channel. If the type is currently Gray, for instance, the returned
109 110
 * type would be GrayA. If the drawable already has an alpha channel,
 * the drawable's type is simply returned.
111
 *
112
 * Returns: The drawable's type with alpha.
113
 **/
114 115
GimpImageType
gimp_drawable_type_with_alpha (gint32 drawable_ID)
Elliot Lee's avatar
Elliot Lee committed
116
{
117
  GimpParam *return_vals;
118
  gint nreturn_vals;
119
  GimpImageType type_with_alpha = 0;
Elliot Lee's avatar
Elliot Lee committed
120

121
  return_vals = gimp_run_procedure ("gimp-drawable-type-with-alpha",
122 123 124
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_END);
Elliot Lee's avatar
Elliot Lee committed
125

126 127
  if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
    type_with_alpha = return_vals[1].data.d_int32;
Elliot Lee's avatar
Elliot Lee committed
128 129 130

  gimp_destroy_params (return_vals, nreturn_vals);

131
  return type_with_alpha;
Elliot Lee's avatar
Elliot Lee committed
132 133
}

134 135 136 137
/**
 * gimp_drawable_has_alpha:
 * @drawable_ID: The drawable.
 *
138
 * Returns TRUE if the drawable has an alpha channel.
139 140 141 142 143 144
 *
 * This procedure returns whether the specified drawable has an alpha
 * channel. This can only be true for layers, and the associated type
 * will be one of: { RGBA , GRAYA, INDEXEDA }.
 *
 * Returns: Does the drawable have an alpha channel?
145
 **/
146 147
gboolean
gimp_drawable_has_alpha (gint32 drawable_ID)
Elliot Lee's avatar
Elliot Lee committed
148
{
149
  GimpParam *return_vals;
150
  gint nreturn_vals;
151
  gboolean has_alpha = FALSE;
Elliot Lee's avatar
Elliot Lee committed
152

153
  return_vals = gimp_run_procedure ("gimp-drawable-has-alpha",
154 155 156
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_END);
Elliot Lee's avatar
Elliot Lee committed
157

158
  if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
159
    has_alpha = return_vals[1].data.d_int32;
Elliot Lee's avatar
Elliot Lee committed
160 161 162

  gimp_destroy_params (return_vals, nreturn_vals);

163
  return has_alpha;
Elliot Lee's avatar
Elliot Lee committed
164 165
}

166 167 168 169 170 171
/**
 * gimp_drawable_is_rgb:
 * @drawable_ID: The drawable.
 *
 * Returns whether the drawable is an RGB type.
 *
172 173
 * This procedure returns TRUE if the specified drawable is of type {
 * RGB, RGBA }.
174
 *
175
 * Returns: TRUE if the drawable is an RGB type.
176
 **/
177
gboolean
Marc Lehmann's avatar
Marc Lehmann committed
178
gimp_drawable_is_rgb (gint32 drawable_ID)
Elliot Lee's avatar
Elliot Lee committed
179
{
180
  GimpParam *return_vals;
181
  gint nreturn_vals;
182
  gboolean is_rgb = FALSE;
Elliot Lee's avatar
Elliot Lee committed
183

184
  return_vals = gimp_run_procedure ("gimp-drawable-is-rgb",
185 186 187
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_END);
Elliot Lee's avatar
Elliot Lee committed
188

189
  if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
190
    is_rgb = return_vals[1].data.d_int32;
Elliot Lee's avatar
Elliot Lee committed
191 192 193

  gimp_destroy_params (return_vals, nreturn_vals);

194
  return is_rgb;
Elliot Lee's avatar
Elliot Lee committed
195 196
}

197 198 199 200 201 202
/**
 * gimp_drawable_is_gray:
 * @drawable_ID: The drawable.
 *
 * Returns whether the drawable is a grayscale type.
 *
203 204
 * This procedure returns TRUE if the specified drawable is of type {
 * Gray, GrayA }.
205
 *
206
 * Returns: TRUE if the drawable is a grayscale type.
207
 **/
208
gboolean
Marc Lehmann's avatar
Marc Lehmann committed
209
gimp_drawable_is_gray (gint32 drawable_ID)
Elliot Lee's avatar
Elliot Lee committed
210
{
211
  GimpParam *return_vals;
212
  gint nreturn_vals;
213
  gboolean is_gray = FALSE;
Elliot Lee's avatar
Elliot Lee committed
214

215
  return_vals = gimp_run_procedure ("gimp-drawable-is-gray",
216 217 218
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_END);
Elliot Lee's avatar
Elliot Lee committed
219

220
  if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
221
    is_gray = return_vals[1].data.d_int32;
Elliot Lee's avatar
Elliot Lee committed
222 223 224

  gimp_destroy_params (return_vals, nreturn_vals);

225
  return is_gray;
Elliot Lee's avatar
Elliot Lee committed
226 227
}

228 229 230 231 232 233
/**
 * gimp_drawable_is_indexed:
 * @drawable_ID: The drawable.
 *
 * Returns whether the drawable is an indexed type.
 *
234 235
 * This procedure returns TRUE if the specified drawable is of type {
 * Indexed, IndexedA }.
236
 *
237
 * Returns: TRUE if the drawable is an indexed type.
238
 **/
239
gboolean
240
gimp_drawable_is_indexed (gint32 drawable_ID)
Elliot Lee's avatar
Elliot Lee committed
241
{
242
  GimpParam *return_vals;
243
  gint nreturn_vals;
244
  gboolean is_indexed = FALSE;
Elliot Lee's avatar
Elliot Lee committed
245

246
  return_vals = gimp_run_procedure ("gimp-drawable-is-indexed",
247 248 249
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_END);
Elliot Lee's avatar
Elliot Lee committed
250

251
  if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
252
    is_indexed = return_vals[1].data.d_int32;
Elliot Lee's avatar
Elliot Lee committed
253 254 255

  gimp_destroy_params (return_vals, nreturn_vals);

256
  return is_indexed;
Elliot Lee's avatar
Elliot Lee committed
257 258
}

259
/**
260
 * gimp_drawable_bpp:
261 262 263 264
 * @drawable_ID: The drawable.
 *
 * Returns the bytes per pixel.
 *
265 266 267
 * This procedure returns the number of bytes per pixel, which
 * corresponds to the number of components unless
 * gimp_plugin_enable_precision() was called.
268 269
 *
 * Returns: Bytes per pixel.
270
 **/
271
gint
272
gimp_drawable_bpp (gint32 drawable_ID)
Elliot Lee's avatar
Elliot Lee committed
273
{
274
  GimpParam *return_vals;
275
  gint nreturn_vals;
276
  gint bpp = 0;
Elliot Lee's avatar
Elliot Lee committed
277

278
  return_vals = gimp_run_procedure ("gimp-drawable-bpp",
279 280 281
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_END);
Elliot Lee's avatar
Elliot Lee committed
282

283
  if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
284
    bpp = return_vals[1].data.d_int32;
Elliot Lee's avatar
Elliot Lee committed
285 286 287

  gimp_destroy_params (return_vals, nreturn_vals);

288
  return bpp;
Elliot Lee's avatar
Elliot Lee committed
289 290
}

291 292 293 294 295 296 297 298 299
/**
 * gimp_drawable_width:
 * @drawable_ID: The drawable.
 *
 * Returns the width of the drawable.
 *
 * This procedure returns the specified drawable's width in pixels.
 *
 * Returns: Width of drawable.
300
 **/
301 302
gint
gimp_drawable_width (gint32 drawable_ID)
Elliot Lee's avatar
Elliot Lee committed
303
{
304
  GimpParam *return_vals;
305 306
  gint nreturn_vals;
  gint width = 0;
Elliot Lee's avatar
Elliot Lee committed
307

308
  return_vals = gimp_run_procedure ("gimp-drawable-width",
309 310 311
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_END);
Elliot Lee's avatar
Elliot Lee committed
312

313
  if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
314
    width = return_vals[1].data.d_int32;
Elliot Lee's avatar
Elliot Lee committed
315 316 317

  gimp_destroy_params (return_vals, nreturn_vals);

318
  return width;
Elliot Lee's avatar
Elliot Lee committed
319 320
}

321 322 323 324 325 326 327 328 329
/**
 * gimp_drawable_height:
 * @drawable_ID: The drawable.
 *
 * Returns the height of the drawable.
 *
 * This procedure returns the specified drawable's height in pixels.
 *
 * Returns: Height of drawable.
330
 **/
331 332
gint
gimp_drawable_height (gint32 drawable_ID)
Elliot Lee's avatar
Elliot Lee committed
333
{
334
  GimpParam *return_vals;
335 336
  gint nreturn_vals;
  gint height = 0;
Elliot Lee's avatar
Elliot Lee committed
337

338
  return_vals = gimp_run_procedure ("gimp-drawable-height",
339 340 341
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_END);
Elliot Lee's avatar
Elliot Lee committed
342

343
  if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
344
    height = return_vals[1].data.d_int32;
Elliot Lee's avatar
Elliot Lee committed
345 346 347

  gimp_destroy_params (return_vals, nreturn_vals);

348
  return height;
Elliot Lee's avatar
Elliot Lee committed
349 350
}

351 352 353 354 355 356 357 358 359 360 361 362 363
/**
 * gimp_drawable_offsets:
 * @drawable_ID: The drawable.
 * @offset_x: x offset of drawable.
 * @offset_y: y offset of drawable.
 *
 * Returns the offsets for the drawable.
 *
 * This procedure returns the specified drawable's offsets. This only
 * makes sense if the drawable is a layer since channels are anchored.
 * The offsets of a channel will be returned as 0.
 *
 * Returns: TRUE on success.
364
 **/
365
gboolean
366
gimp_drawable_offsets (gint32  drawable_ID,
367 368
                       gint   *offset_x,
                       gint   *offset_y)
Elliot Lee's avatar
Elliot Lee committed
369
{
370
  GimpParam *return_vals;
371
  gint nreturn_vals;
372
  gboolean success = TRUE;
Elliot Lee's avatar
Elliot Lee committed
373

374
  return_vals = gimp_run_procedure ("gimp-drawable-offsets",
375 376 377
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_END);
Elliot Lee's avatar
Elliot Lee committed
378

379 380 381
  *offset_x = 0;
  *offset_y = 0;

382 383 384
  success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;

  if (success)
Elliot Lee's avatar
Elliot Lee committed
385
    {
386 387
      *offset_x = return_vals[1].data.d_int32;
      *offset_y = return_vals[2].data.d_int32;
Elliot Lee's avatar
Elliot Lee committed
388 389 390
    }

  gimp_destroy_params (return_vals, nreturn_vals);
391 392

  return success;
393 394
}

395 396 397 398 399 400 401 402 403 404 405
/**
 * gimp_drawable_mask_bounds:
 * @drawable_ID: The drawable.
 * @x1: x coordinate of the upper left corner of selection bounds.
 * @y1: y coordinate of the upper left corner of selection bounds.
 * @x2: x coordinate of the lower right corner of selection bounds.
 * @y2: y coordinate of the lower right corner of selection bounds.
 *
 * Find the bounding box of the current selection in relation to the
 * specified drawable.
 *
406
 * This procedure returns whether there is a selection. If there is
Sven Neumann's avatar
Sven Neumann committed
407
 * one, the upper left and lower right-hand corners of its bounding box
408 409
 * are returned. These coordinates are specified relative to the
 * drawable's origin, and bounded by the drawable's extents. Please
Sven Neumann's avatar
Sven Neumann committed
410
 * note that the pixel specified by the lower right-hand coordinate of
411 412 413
 * the bounding box is not part of the selection. The selection ends at
 * the upper left corner of this pixel. This means the width of the
 * selection can be calculated as (x2 - x1), its height as (y2 - y1).
414 415 416 417
 * Note that the returned boolean does NOT correspond with the returned
 * region being empty or not, it always returns whether the selection
 * is non_empty. See gimp_drawable_mask_intersect() for a boolean
 * return value which is more useful in most cases.
418 419
 *
 * Returns: TRUE if there is a selection.
420
 **/
421 422
gboolean
gimp_drawable_mask_bounds (gint32  drawable_ID,
423 424 425 426
                           gint   *x1,
                           gint   *y1,
                           gint   *x2,
                           gint   *y2)
427 428 429 430 431
{
  GimpParam *return_vals;
  gint nreturn_vals;
  gboolean non_empty = FALSE;

432
  return_vals = gimp_run_procedure ("gimp-drawable-mask-bounds",
433 434 435
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_END);
436 437 438 439 440 441 442 443 444 445 446 447 448 449 450

  if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
    {
      non_empty = return_vals[1].data.d_int32;
      *x1 = return_vals[2].data.d_int32;
      *y1 = return_vals[3].data.d_int32;
      *x2 = return_vals[4].data.d_int32;
      *y2 = return_vals[5].data.d_int32;
    }

  gimp_destroy_params (return_vals, nreturn_vals);

  return non_empty;
}

451 452 453 454 455 456 457 458 459 460 461 462 463
/**
 * gimp_drawable_mask_intersect:
 * @drawable_ID: The drawable.
 * @x: x coordinate of the upper left corner of the intersection.
 * @y: y coordinate of the upper left corner of the intersection.
 * @width: width of the intersection.
 * @height: height of the intersection.
 *
 * Find the bounding box of the current selection in relation to the
 * specified drawable.
 *
 * This procedure returns whether there is an intersection between the
 * drawable and the selection. Unlike gimp_drawable_mask_bounds(), the
464 465 466
 * intersection's bounds are returned as x, y, width, height.
 * If there is no selection this function returns TRUE and the returned
 * bounds are the extents of the whole drawable.
467 468 469
 *
 * Returns: TRUE if the returned area is not empty.
 *
470
 * Since: 2.2
471
 **/
472 473
gboolean
gimp_drawable_mask_intersect (gint32  drawable_ID,
474 475 476 477
                              gint   *x,
                              gint   *y,
                              gint   *width,
                              gint   *height)
478 479 480 481 482
{
  GimpParam *return_vals;
  gint nreturn_vals;
  gboolean non_empty = FALSE;

483
  return_vals = gimp_run_procedure ("gimp-drawable-mask-intersect",
484 485 486
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_END);
487 488 489 490 491 492 493 494 495 496 497 498 499 500 501

  if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
    {
      non_empty = return_vals[1].data.d_int32;
      *x = return_vals[2].data.d_int32;
      *y = return_vals[3].data.d_int32;
      *width = return_vals[4].data.d_int32;
      *height = return_vals[5].data.d_int32;
    }

  gimp_destroy_params (return_vals, nreturn_vals);

  return non_empty;
}

502 503 504 505 506 507 508
/**
 * gimp_drawable_merge_shadow:
 * @drawable_ID: The drawable.
 * @undo: Push merge to undo stack?
 *
 * Merge the shadow buffer with the specified drawable.
 *
509
 * This procedure combines the contents of the drawable's shadow buffer
510
 * (for temporary processing) with the specified drawable. The 'undo'
511 512 513 514
 * parameter specifies whether to add an undo step for the operation.
 * Requesting no undo is useful for such applications as 'auto-apply'.
 *
 * Returns: TRUE on success.
515
 **/
516 517
gboolean
gimp_drawable_merge_shadow (gint32   drawable_ID,
518
                            gboolean undo)
519 520 521 522 523
{
  GimpParam *return_vals;
  gint nreturn_vals;
  gboolean success = TRUE;

524
  return_vals = gimp_run_procedure ("gimp-drawable-merge-shadow",
525 526 527 528
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_INT32, undo,
                                    GIMP_PDB_END);
529 530 531 532 533 534 535 536

  success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;

  gimp_destroy_params (return_vals, nreturn_vals);

  return success;
}

537 538 539 540 541 542 543 544 545 546 547 548 549
/**
 * gimp_drawable_free_shadow:
 * @drawable_ID: The drawable.
 *
 * Free the specified drawable's shadow data (if it exists).
 *
 * This procedure is intended as a memory saving device. If any shadow
 * memory has been allocated, it will be freed automatically when the
 * drawable is removed from the image, or when the plug-in procedure
 * which allocated it returns.
 *
 * Returns: TRUE on success.
 *
550
 * Since: 2.6
551
 **/
552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570
gboolean
gimp_drawable_free_shadow (gint32 drawable_ID)
{
  GimpParam *return_vals;
  gint nreturn_vals;
  gboolean success = TRUE;

  return_vals = gimp_run_procedure ("gimp-drawable-free-shadow",
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_END);

  success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;

  gimp_destroy_params (return_vals, nreturn_vals);

  return success;
}

571 572 573 574 575 576 577 578 579 580 581 582
/**
 * gimp_drawable_update:
 * @drawable_ID: The drawable.
 * @x: x coordinate of upper left corner of update region.
 * @y: y coordinate of upper left corner of update region.
 * @width: Width of update region.
 * @height: Height of update region.
 *
 * Update the specified region of the drawable.
 *
 * This procedure updates the specified region of the drawable. The (x,
 * y) coordinate pair is relative to the drawable's origin, not to the
Sven Neumann's avatar
Sven Neumann committed
583 584
 * image origin. Therefore, the entire drawable can be updated using
 * (0, 0, width, height).
585 586
 *
 * Returns: TRUE on success.
587
 **/
588 589
gboolean
gimp_drawable_update (gint32 drawable_ID,
590 591 592 593
                      gint   x,
                      gint   y,
                      gint   width,
                      gint   height)
594 595 596 597 598
{
  GimpParam *return_vals;
  gint nreturn_vals;
  gboolean success = TRUE;

599
  return_vals = gimp_run_procedure ("gimp-drawable-update",
600 601 602 603 604 605 606
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_INT32, x,
                                    GIMP_PDB_INT32, y,
                                    GIMP_PDB_INT32, width,
                                    GIMP_PDB_INT32, height,
                                    GIMP_PDB_END);
607 608 609 610 611 612 613 614

  success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;

  gimp_destroy_params (return_vals, nreturn_vals);

  return success;
}

615 616 617 618 619 620 621 622 623 624 625 626 627 628
/**
 * gimp_drawable_get_pixel:
 * @drawable_ID: The drawable.
 * @x_coord: The x coordinate.
 * @y_coord: The y coordinate.
 * @num_channels: The number of channels for the pixel.
 *
 * Gets the value of the pixel at the specified coordinates.
 *
 * This procedure gets the pixel value at the specified coordinates.
 * The 'num_channels' argument must always be equal to the
 * bytes-per-pixel value for the specified drawable.
 *
 * Returns: The pixel value.
629
 **/
630 631
guint8 *
gimp_drawable_get_pixel (gint32  drawable_ID,
632 633 634
                         gint    x_coord,
                         gint    y_coord,
                         gint   *num_channels)
635 636 637 638 639
{
  GimpParam *return_vals;
  gint nreturn_vals;
  guint8 *pixel = NULL;

640
  return_vals = gimp_run_procedure ("gimp-drawable-get-pixel",
641 642 643 644 645
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_INT32, x_coord,
                                    GIMP_PDB_INT32, y_coord,
                                    GIMP_PDB_END);
646 647 648 649 650 651 652

  *num_channels = 0;

  if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
    {
      *num_channels = return_vals[1].data.d_int32;
      pixel = g_new (guint8, *num_channels);
653 654 655
      memcpy (pixel,
              return_vals[2].data.d_int8array,
              *num_channels * sizeof (guint8));
656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674
    }

  gimp_destroy_params (return_vals, nreturn_vals);

  return pixel;
}

/**
 * gimp_drawable_set_pixel:
 * @drawable_ID: The drawable.
 * @x_coord: The x coordinate.
 * @y_coord: The y coordinate.
 * @num_channels: The number of channels for the pixel.
 * @pixel: The pixel value.
 *
 * Sets the value of the pixel at the specified coordinates.
 *
 * This procedure sets the pixel value at the specified coordinates.
 * The 'num_channels' argument must always be equal to the
675
 * bytes-per-pixel value for the specified drawable. Note that this
676 677 678 679
 * function is not undoable, you should use it only on drawables you
 * just created yourself.
 *
 * Returns: TRUE on success.
680
 **/
681 682
gboolean
gimp_drawable_set_pixel (gint32        drawable_ID,
683 684 685 686
                         gint          x_coord,
                         gint          y_coord,
                         gint          num_channels,
                         const guint8 *pixel)
687 688 689 690 691
{
  GimpParam *return_vals;
  gint nreturn_vals;
  gboolean success = TRUE;

692
  return_vals = gimp_run_procedure ("gimp-drawable-set-pixel",
693 694 695 696 697 698 699
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_INT32, x_coord,
                                    GIMP_PDB_INT32, y_coord,
                                    GIMP_PDB_INT32, num_channels,
                                    GIMP_PDB_INT8ARRAY, pixel,
                                    GIMP_PDB_END);
700 701 702 703 704 705 706 707

  success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;

  gimp_destroy_params (return_vals, nreturn_vals);

  return success;
}

708
/**
709
 * gimp_drawable_fill:
710
 * @drawable_ID: The drawable.
711
 * @fill_type: The type of fill.
712
 *
713
 * Fill the drawable with the specified fill mode.
714
 *
715 716 717 718 719 720
 * This procedure fills the drawable. If the fill mode is foreground
 * the current foreground color is used. If the fill mode is
 * background, the current background color is used. If the fill type
 * is white, then white is used. Transparent fill only affects layers
 * with an alpha channel, in which case the alpha channel is set to
 * transparent. If the drawable has no alpha channel, it is filled to
721 722 723 724 725
 * white. No fill leaves the drawable's contents undefined.
 * This procedure is unlike gimp_edit_fill() or the bucket fill tool
 * because it fills regardless of a selection. Its main purpose is to
 * fill a newly created drawable before adding it to the image. This
 * operation cannot be undone.
726 727
 *
 * Returns: TRUE on success.
728
 **/
729
gboolean
730
gimp_drawable_fill (gint32       drawable_ID,
731
                    GimpFillType fill_type)
732
{
733
  GimpParam *return_vals;
734
  gint nreturn_vals;
735
  gboolean success = TRUE;
736

737
  return_vals = gimp_run_procedure ("gimp-drawable-fill",
738 739 740 741
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_INT32, fill_type,
                                    GIMP_PDB_END);
742

743 744
  success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;

745
  gimp_destroy_params (return_vals, nreturn_vals);
746 747

  return success;
748
}
749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765

/**
 * gimp_drawable_offset:
 * @drawable_ID: The drawable to offset.
 * @wrap_around: wrap image around or fill vacated regions.
 * @fill_type: fill vacated regions of drawable with background or transparent.
 * @offset_x: offset by this amount in X direction.
 * @offset_y: offset by this amount in Y direction.
 *
 * Offset the drawable by the specified amounts in the X and Y
 * directions
 *
 * This procedure offsets the specified drawable by the amounts
 * specified by 'offset_x' and 'offset_y'. If 'wrap_around' is set to
 * TRUE, then portions of the drawable which are offset out of bounds
 * are wrapped around. Alternatively, the undefined regions of the
 * drawable can be filled with transparency or the background color, as
766
 * specified by the 'fill-type' parameter.
767 768
 *
 * Returns: TRUE on success.
769
 **/
770 771
gboolean
gimp_drawable_offset (gint32         drawable_ID,
772 773 774 775
                      gboolean       wrap_around,
                      GimpOffsetType fill_type,
                      gint           offset_x,
                      gint           offset_y)
776 777 778 779 780
{
  GimpParam *return_vals;
  gint nreturn_vals;
  gboolean success = TRUE;

781
  return_vals = gimp_run_procedure ("gimp-drawable-offset",
782 783 784 785 786 787 788
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_INT32, wrap_around,
                                    GIMP_PDB_INT32, fill_type,
                                    GIMP_PDB_INT32, offset_x,
                                    GIMP_PDB_INT32, offset_y,
                                    GIMP_PDB_END);
789 790 791 792 793 794 795

  success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;

  gimp_destroy_params (return_vals, nreturn_vals);

  return success;
}
796 797

/**
798 799
 * _gimp_drawable_thumbnail:
 * @drawable_ID: The drawable.
800 801 802 803
 * @width: The requested thumbnail width.
 * @height: The requested thumbnail height.
 * @actual_width: The previews width.
 * @actual_height: The previews height.
804 805 806
 * @bpp: The previews bpp.
 * @thumbnail_data_count: The number of bytes in thumbnail data.
 * @thumbnail_data: The thumbnail data.
807
 *
808
 * Get a thumbnail of a drawable.
809
 *
810
 * This function gets data from which a thumbnail of a drawable preview
811
 * can be created. Maximum x or y dimension is 1024 pixels. The pixels
812 813
 * are returned in RGB[A] or GRAY[A] format. The bpp return value gives
 * the number of bytes in the image.
814 815
 *
 * Returns: TRUE on success.
816
 **/
817
gboolean
818
_gimp_drawable_thumbnail (gint32   drawable_ID,
819 820 821 822 823 824 825
                          gint     width,
                          gint     height,
                          gint    *actual_width,
                          gint    *actual_height,
                          gint    *bpp,
                          gint    *thumbnail_data_count,
                          guint8 **thumbnail_data)
826 827 828 829 830
{
  GimpParam *return_vals;
  gint nreturn_vals;
  gboolean success = TRUE;

831
  return_vals = gimp_run_procedure ("gimp-drawable-thumbnail",
832 833 834 835 836
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_INT32, width,
                                    GIMP_PDB_INT32, height,
                                    GIMP_PDB_END);
837

838 839
  *actual_width = 0;
  *actual_height = 0;
840 841 842 843
  *bpp = 0;
  *thumbnail_data_count = 0;
  *thumbnail_data = NULL;

844 845
  success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;

846 847
  if (success)
    {
848 849
      *actual_width = return_vals[1].data.d_int32;
      *actual_height = return_vals[2].data.d_int32;
850 851 852
      *bpp = return_vals[3].data.d_int32;
      *thumbnail_data_count = return_vals[4].data.d_int32;
      *thumbnail_data = g_new (guint8, *thumbnail_data_count);
853 854 855
      memcpy (*thumbnail_data,
              return_vals[5].data.d_int8array,
              *thumbnail_data_count * sizeof (guint8));
856 857
    }

858 859 860 861
  gimp_destroy_params (return_vals, nreturn_vals);

  return success;
}
862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880

/**
 * _gimp_drawable_sub_thumbnail:
 * @drawable_ID: The drawable.
 * @src_x: The x coordinate of the area.
 * @src_y: The y coordinate of the area.
 * @src_width: The width of the area.
 * @src_height: The height of the area.
 * @dest_width: The thumbnail width.
 * @dest_height: The thumbnail height.
 * @width: The previews width.
 * @height: The previews height.
 * @bpp: The previews bpp.
 * @thumbnail_data_count: The number of bytes in thumbnail data.
 * @thumbnail_data: The thumbnail data.
 *
 * Get a thumbnail of a sub-area of a drawable drawable.
 *
 * This function gets data from which a thumbnail of a drawable preview
881
 * can be created. Maximum x or y dimension is 1024 pixels. The pixels
882 883 884 885 886
 * are returned in RGB[A] or GRAY[A] format. The bpp return value gives
 * the number of bytes in the image.
 *
 * Returns: TRUE on success.
 *
887
 * Since: 2.2
888
 **/
889 890
gboolean
_gimp_drawable_sub_thumbnail (gint32   drawable_ID,
891 892 893 894 895 896 897 898 899 900 901
                              gint     src_x,
                              gint     src_y,
                              gint     src_width,
                              gint     src_height,
                              gint     dest_width,
                              gint     dest_height,
                              gint    *width,
                              gint    *height,
                              gint    *bpp,
                              gint    *thumbnail_data_count,
                              guint8 **thumbnail_data)
902 903 904 905 906
{
  GimpParam *return_vals;
  gint nreturn_vals;
  gboolean success = TRUE;

907
  return_vals = gimp_run_procedure ("gimp-drawable-sub-thumbnail",
908 909 910 911 912 913 914 915 916
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_INT32, src_x,
                                    GIMP_PDB_INT32, src_y,
                                    GIMP_PDB_INT32, src_width,
                                    GIMP_PDB_INT32, src_height,
                                    GIMP_PDB_INT32, dest_width,
                                    GIMP_PDB_INT32, dest_height,
                                    GIMP_PDB_END);
917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932

  *width = 0;
  *height = 0;
  *bpp = 0;
  *thumbnail_data_count = 0;
  *thumbnail_data = NULL;

  success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;

  if (success)
    {
      *width = return_vals[1].data.d_int32;
      *height = return_vals[2].data.d_int32;
      *bpp = return_vals[3].data.d_int32;
      *thumbnail_data_count = return_vals[4].data.d_int32;
      *thumbnail_data = g_new (guint8, *thumbnail_data_count);
933 934 935
      memcpy (*thumbnail_data,
              return_vals[5].data.d_int8array,
              *thumbnail_data_count * sizeof (guint8));
936 937 938 939 940 941
    }

  gimp_destroy_params (return_vals, nreturn_vals);

  return success;
}
942 943 944 945

/**
 * gimp_drawable_foreground_extract:
 * @drawable_ID: The drawable.
946
 * @mode: The algorithm to use.
947 948 949 950 951
 * @mask_ID: Tri-Map.
 *
 * Extract the foreground of a drawable using a given trimap.
 *
 * Image Segmentation by Uniform Color Clustering, see
952
 * https://www.inf.fu-berlin.de/inst/pubs/tr-b-05-07.pdf
953 954 955
 *
 * Returns: TRUE on success.
 *
956
 * Since: 2.4
957
 **/
958
gboolean
959
gimp_drawable_foreground_extract (gint32                    drawable_ID,
960 961
                                  GimpForegroundExtractMode mode,
                                  gint32                    mask_ID)
962 963 964 965 966
{
  GimpParam *return_vals;
  gint nreturn_vals;
  gboolean success = TRUE;

967
  return_vals = gimp_run_procedure ("gimp-drawable-foreground-extract",
968 969 970 971 972
                                    &nreturn_vals,
                                    GIMP_PDB_DRAWABLE, drawable_ID,
                                    GIMP_PDB_INT32, mode,
                                    GIMP_PDB_DRAWABLE, mask_ID,
                                    GIMP_PDB_END);
973 974 975 976 977 978 979

  success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;

  gimp_destroy_params (return_vals, nreturn_vals);

  return success;
}