home *** CD-ROM | disk | FTP | other *** search
/ PC Pro 2002 April / pcpro0402.iso / essentials / graphics / Gimp / gimp-src-20001226.exe / src / gimp / libgimp / gimpimage_pdb.c < prev    next >
Encoding:
C/C++ Source or Header  |  2000-08-25  |  58.3 KB  |  2,167 lines
  1. /* LIBGIMP - The GIMP Library
  2.  * Copyright (C) 1995-2000 Peter Mattis and Spencer Kimball
  3.  *
  4.  * gimpimage_pdb.c
  5.  *
  6.  * This library is free software; you can redistribute it and/or
  7.  * modify it under the terms of the GNU Lesser General Public
  8.  * License as published by the Free Software Foundation; either
  9.  * version 2 of the License, or (at your option) any later version.
  10.  *
  11.  * This library is distributed in the hope that it will be useful,
  12.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14.  * Lesser General Public License for more details.
  15.  *
  16.  * You should have received a copy of the GNU Lesser General Public
  17.  * License along with this library; if not, write to the
  18.  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19.  * Boston, MA 02111-1307, USA.
  20.  */
  21.  
  22. /* NOTE: This file is autogenerated by pdbgen.pl */
  23.  
  24. #include "gimp.h"
  25.  
  26. /**
  27.  * gimp_image_list:
  28.  * @num_images: The number of images currently open.
  29.  *
  30.  * Returns the list of images currently open.
  31.  *
  32.  * This procedure returns the list of images currently open in the
  33.  * GIMP.
  34.  *
  35.  * Returns: The list of images currently open.
  36.  */
  37. gint *
  38. gimp_image_list (gint *num_images)
  39. {
  40.   GimpParam *return_vals;
  41.   gint nreturn_vals;
  42.   gint *image_ids = NULL;
  43.  
  44.   return_vals = gimp_run_procedure ("gimp_image_list",
  45.                     &nreturn_vals,
  46.                     GIMP_PDB_END);
  47.  
  48.   *num_images = 0;
  49.  
  50.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  51.     {
  52.       *num_images = return_vals[1].data.d_int32;
  53.       image_ids = g_new (gint32, *num_images);
  54.       memcpy (image_ids, return_vals[2].data.d_int32array,
  55.           *num_images * sizeof (gint32));
  56.     }
  57.  
  58.   gimp_destroy_params (return_vals, nreturn_vals);
  59.  
  60.   return image_ids;
  61. }
  62.  
  63. /**
  64.  * gimp_image_new:
  65.  * @width: The width of the image.
  66.  * @height: The height of the image.
  67.  * @type: The type of image.
  68.  *
  69.  * Creates a new image with the specified width, height, and type.
  70.  *
  71.  * Creates a new image, undisplayed with the specified extents and
  72.  * type. A layer should be created and added before this image is
  73.  * displayed, or subsequent calls to 'gimp_display_new' with this image
  74.  * as an argument will fail. Layers can be created using the
  75.  * 'gimp_layer_new' commands. They can be added to an image using the
  76.  * 'gimp_image_add_layer' command.
  77.  *
  78.  * Returns: The ID of the newly created image.
  79.  */
  80. gint32
  81. gimp_image_new (gint              width,
  82.         gint              height,
  83.         GimpImageBaseType type)
  84. {
  85.   GimpParam *return_vals;
  86.   gint nreturn_vals;
  87.   gint32 image_ID = -1;
  88.  
  89.   return_vals = gimp_run_procedure ("gimp_image_new",
  90.                     &nreturn_vals,
  91.                     GIMP_PDB_INT32, width,
  92.                     GIMP_PDB_INT32, height,
  93.                     GIMP_PDB_INT32, type,
  94.                     GIMP_PDB_END);
  95.  
  96.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  97.     image_ID = return_vals[1].data.d_image;
  98.  
  99.   gimp_destroy_params (return_vals, nreturn_vals);
  100.  
  101.   return image_ID;
  102. }
  103.  
  104. /**
  105.  * gimp_image_resize:
  106.  * @image_ID: The image.
  107.  * @new_width: New image width.
  108.  * @new_height: New image height.
  109.  * @offx: x offset between upper left corner of old and new images: (new - old).
  110.  * @offy: y offset between upper left corner of old and new images: (new - old).
  111.  *
  112.  * Resize the image to the specified extents.
  113.  *
  114.  * This procedure resizes the image so that it's new width and height
  115.  * are equal to the supplied parameters. Offsets are also provided
  116.  * which describe the position of the previous image's content. No
  117.  * bounds checking is currently provided, so don't supply parameters
  118.  * that are out of bounds. All channels within the image are resized
  119.  * according to the specified parameters; this includes the image
  120.  * selection mask. All layers within the image are repositioned
  121.  * according to the specified offsets.
  122.  *
  123.  * Returns: TRUE on success.
  124.  */
  125. gboolean
  126. gimp_image_resize (gint32 image_ID,
  127.            gint   new_width,
  128.            gint   new_height,
  129.            gint   offx,
  130.            gint   offy)
  131. {
  132.   GimpParam *return_vals;
  133.   gint nreturn_vals;
  134.   gboolean success = TRUE;
  135.  
  136.   return_vals = gimp_run_procedure ("gimp_image_resize",
  137.                     &nreturn_vals,
  138.                     GIMP_PDB_IMAGE, image_ID,
  139.                     GIMP_PDB_INT32, new_width,
  140.                     GIMP_PDB_INT32, new_height,
  141.                     GIMP_PDB_INT32, offx,
  142.                     GIMP_PDB_INT32, offy,
  143.                     GIMP_PDB_END);
  144.  
  145.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  146.  
  147.   gimp_destroy_params (return_vals, nreturn_vals);
  148.  
  149.   return success;
  150. }
  151.  
  152. /**
  153.  * gimp_image_scale:
  154.  * @image_ID: The image.
  155.  * @new_width: New image width.
  156.  * @new_height: New image height.
  157.  *
  158.  * Scale the image to the specified extents.
  159.  *
  160.  * This procedure scales the image so that it's new width and height
  161.  * are equal to the supplied parameters. Offsets are also provided
  162.  * which describe the position of the previous image's content. No
  163.  * bounds checking is currently provided, so don't supply parameters
  164.  * that are out of bounds. All channels within the image are scaled
  165.  * according to the specified parameters; this includes the image
  166.  * selection mask. All layers within the image are repositioned
  167.  * according to the specified offsets.
  168.  *
  169.  * Returns: TRUE on success.
  170.  */
  171. gboolean
  172. gimp_image_scale (gint32 image_ID,
  173.           gint   new_width,
  174.           gint   new_height)
  175. {
  176.   GimpParam *return_vals;
  177.   gint nreturn_vals;
  178.   gboolean success = TRUE;
  179.  
  180.   return_vals = gimp_run_procedure ("gimp_image_scale",
  181.                     &nreturn_vals,
  182.                     GIMP_PDB_IMAGE, image_ID,
  183.                     GIMP_PDB_INT32, new_width,
  184.                     GIMP_PDB_INT32, new_height,
  185.                     GIMP_PDB_END);
  186.  
  187.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  188.  
  189.   gimp_destroy_params (return_vals, nreturn_vals);
  190.  
  191.   return success;
  192. }
  193.  
  194. /**
  195.  * gimp_image_delete:
  196.  * @image_ID: The image.
  197.  *
  198.  * Delete the specified image.
  199.  *
  200.  * If there are no displays associated with this image it will be
  201.  * deleted. This means that you can not delete an image through the PDB
  202.  * that was created by the user. If the associated display was however
  203.  * created through the PDB and you know the display ID, you may delete
  204.  * the display. Removal of the last associated display will then delete
  205.  * the image.
  206.  *
  207.  * Returns: TRUE on success.
  208.  */
  209. gboolean
  210. gimp_image_delete (gint32 image_ID)
  211. {
  212.   GimpParam *return_vals;
  213.   gint nreturn_vals;
  214.   gboolean success = TRUE;
  215.  
  216.   return_vals = gimp_run_procedure ("gimp_image_delete",
  217.                     &nreturn_vals,
  218.                     GIMP_PDB_IMAGE, image_ID,
  219.                     GIMP_PDB_END);
  220.  
  221.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  222.  
  223.   gimp_destroy_params (return_vals, nreturn_vals);
  224.  
  225.   return success;
  226. }
  227.  
  228. /**
  229.  * gimp_image_free_shadow:
  230.  * @image_ID: The image.
  231.  *
  232.  * Free the specified image's shadow data (if it exists).
  233.  *
  234.  * This procedure is intended as a memory saving device. If any shadow
  235.  * memory has been allocated, it will be freed automatically on a call
  236.  * to 'gimp_image_delete'.
  237.  *
  238.  * Returns: TRUE on success.
  239.  */
  240. gboolean
  241. gimp_image_free_shadow (gint32 image_ID)
  242. {
  243.   GimpParam *return_vals;
  244.   gint nreturn_vals;
  245.   gboolean success = TRUE;
  246.  
  247.   return_vals = gimp_run_procedure ("gimp_image_free_shadow",
  248.                     &nreturn_vals,
  249.                     GIMP_PDB_IMAGE, image_ID,
  250.                     GIMP_PDB_END);
  251.  
  252.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  253.  
  254.   gimp_destroy_params (return_vals, nreturn_vals);
  255.  
  256.   return success;
  257. }
  258.  
  259. /**
  260.  * gimp_image_get_layers:
  261.  * @image_ID: The image.
  262.  * @num_layers: The number of layers contained in the image.
  263.  *
  264.  * Returns the list of layers contained in the specified image.
  265.  *
  266.  * This procedure returns the list of layers contained in the specified
  267.  * image. The order of layers is from topmost to bottommost.
  268.  *
  269.  * Returns: The list of layers contained in the image.
  270.  */
  271. gint *
  272. gimp_image_get_layers (gint32  image_ID,
  273.                gint   *num_layers)
  274. {
  275.   GimpParam *return_vals;
  276.   gint nreturn_vals;
  277.   gint *layer_ids = NULL;
  278.  
  279.   return_vals = gimp_run_procedure ("gimp_image_get_layers",
  280.                     &nreturn_vals,
  281.                     GIMP_PDB_IMAGE, image_ID,
  282.                     GIMP_PDB_END);
  283.  
  284.   *num_layers = 0;
  285.  
  286.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  287.     {
  288.       *num_layers = return_vals[1].data.d_int32;
  289.       layer_ids = g_new (gint32, *num_layers);
  290.       memcpy (layer_ids, return_vals[2].data.d_int32array,
  291.           *num_layers * sizeof (gint32));
  292.     }
  293.  
  294.   gimp_destroy_params (return_vals, nreturn_vals);
  295.  
  296.   return layer_ids;
  297. }
  298.  
  299. /**
  300.  * gimp_image_get_channels:
  301.  * @image_ID: The image.
  302.  * @num_channels: The number of channels contained in the image.
  303.  *
  304.  * Returns the list of channels contained in the specified image.
  305.  *
  306.  * This procedure returns the list of channels contained in the
  307.  * specified image. This does not include the selection mask, or layer
  308.  * masks. The order is from topmost to bottommost.
  309.  *
  310.  * Returns: The list of channels contained in the image.
  311.  */
  312. gint *
  313. gimp_image_get_channels (gint32  image_ID,
  314.              gint   *num_channels)
  315. {
  316.   GimpParam *return_vals;
  317.   gint nreturn_vals;
  318.   gint *channel_ids = NULL;
  319.  
  320.   return_vals = gimp_run_procedure ("gimp_image_get_channels",
  321.                     &nreturn_vals,
  322.                     GIMP_PDB_IMAGE, image_ID,
  323.                     GIMP_PDB_END);
  324.  
  325.   *num_channels = 0;
  326.  
  327.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  328.     {
  329.       *num_channels = return_vals[1].data.d_int32;
  330.       channel_ids = g_new (gint32, *num_channels);
  331.       memcpy (channel_ids, return_vals[2].data.d_int32array,
  332.           *num_channels * sizeof (gint32));
  333.     }
  334.  
  335.   gimp_destroy_params (return_vals, nreturn_vals);
  336.  
  337.   return channel_ids;
  338. }
  339.  
  340. /**
  341.  * gimp_image_unset_active_channel:
  342.  * @image_ID: The image.
  343.  *
  344.  * Unsets the active channel in the specified image.
  345.  *
  346.  * If an active channel exists, it is unset. There then exists no
  347.  * active channel, and if desired, one can be set through a call to
  348.  * 'Set Active Channel'. No error is returned in the case of no
  349.  * existing active channel.
  350.  *
  351.  * Returns: TRUE on success.
  352.  */
  353. gboolean
  354. gimp_image_unset_active_channel (gint32 image_ID)
  355. {
  356.   GimpParam *return_vals;
  357.   gint nreturn_vals;
  358.   gboolean success = TRUE;
  359.  
  360.   return_vals = gimp_run_procedure ("gimp_image_unset_active_channel",
  361.                     &nreturn_vals,
  362.                     GIMP_PDB_IMAGE, image_ID,
  363.                     GIMP_PDB_END);
  364.  
  365.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  366.  
  367.   gimp_destroy_params (return_vals, nreturn_vals);
  368.  
  369.   return success;
  370. }
  371.  
  372. /**
  373.  * gimp_image_pick_correlate_layer:
  374.  * @image_ID: The image.
  375.  * @x: The x coordinate for the pick.
  376.  * @y: The y coordinate for the pick.
  377.  *
  378.  * Find the layer visible at the specified coordinates.
  379.  *
  380.  * This procedure finds the layer which is visible at the specified
  381.  * coordinates. Layers which do not qualify are those whose extents do
  382.  * not pass within the specified coordinates, or which are transparent
  383.  * at the specified coordinates. This procedure will return -1 if no
  384.  * layer is found.
  385.  *
  386.  * Returns: The layer found at the specified coordinates.
  387.  */
  388. gint32
  389. gimp_image_pick_correlate_layer (gint32 image_ID,
  390.                  gint   x,
  391.                  gint   y)
  392. {
  393.   GimpParam *return_vals;
  394.   gint nreturn_vals;
  395.   gint32 layer_ID = -1;
  396.  
  397.   return_vals = gimp_run_procedure ("gimp_image_pick_correlate_layer",
  398.                     &nreturn_vals,
  399.                     GIMP_PDB_IMAGE, image_ID,
  400.                     GIMP_PDB_INT32, x,
  401.                     GIMP_PDB_INT32, y,
  402.                     GIMP_PDB_END);
  403.  
  404.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  405.     layer_ID = return_vals[1].data.d_layer;
  406.  
  407.   gimp_destroy_params (return_vals, nreturn_vals);
  408.  
  409.   return layer_ID;
  410. }
  411.  
  412. /**
  413.  * gimp_image_raise_layer:
  414.  * @image_ID: The image.
  415.  * @layer_ID: The layer to raise.
  416.  *
  417.  * Raise the specified layer in the image's layer stack
  418.  *
  419.  * This procedure raises the specified layer one step in the existing
  420.  * layer stack. It will not move the layer if there is no layer above
  421.  * it, or the layer has no alpha channel.
  422.  *
  423.  * Returns: TRUE on success.
  424.  */
  425. gboolean
  426. gimp_image_raise_layer (gint32 image_ID,
  427.             gint32 layer_ID)
  428. {
  429.   GimpParam *return_vals;
  430.   gint nreturn_vals;
  431.   gboolean success = TRUE;
  432.  
  433.   return_vals = gimp_run_procedure ("gimp_image_raise_layer",
  434.                     &nreturn_vals,
  435.                     GIMP_PDB_IMAGE, image_ID,
  436.                     GIMP_PDB_LAYER, layer_ID,
  437.                     GIMP_PDB_END);
  438.  
  439.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  440.  
  441.   gimp_destroy_params (return_vals, nreturn_vals);
  442.  
  443.   return success;
  444. }
  445.  
  446. /**
  447.  * gimp_image_lower_layer:
  448.  * @image_ID: The image.
  449.  * @layer_ID: The layer to lower.
  450.  *
  451.  * Lower the specified layer in the image's layer stack
  452.  *
  453.  * This procedure lowers the specified layer one step in the existing
  454.  * layer stack. It will not move the layer if there is no layer below
  455.  * it, or the layer has no alpha channel.
  456.  *
  457.  * Returns: TRUE on success.
  458.  */
  459. gboolean
  460. gimp_image_lower_layer (gint32 image_ID,
  461.             gint32 layer_ID)
  462. {
  463.   GimpParam *return_vals;
  464.   gint nreturn_vals;
  465.   gboolean success = TRUE;
  466.  
  467.   return_vals = gimp_run_procedure ("gimp_image_lower_layer",
  468.                     &nreturn_vals,
  469.                     GIMP_PDB_IMAGE, image_ID,
  470.                     GIMP_PDB_LAYER, layer_ID,
  471.                     GIMP_PDB_END);
  472.  
  473.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  474.  
  475.   gimp_destroy_params (return_vals, nreturn_vals);
  476.  
  477.   return success;
  478. }
  479.  
  480. /**
  481.  * gimp_image_raise_layer_to_top:
  482.  * @image_ID: The image.
  483.  * @layer_ID: The layer to raise to top.
  484.  *
  485.  * Raise the specified layer in the image's layer stack to top of stack
  486.  *
  487.  * This procedure raises the specified layer to top of the existing
  488.  * layer stack. It will not move the layer if there is no layer above
  489.  * it, or the layer has no alpha channel.
  490.  *
  491.  * Returns: TRUE on success.
  492.  */
  493. gboolean
  494. gimp_image_raise_layer_to_top (gint32 image_ID,
  495.                    gint32 layer_ID)
  496. {
  497.   GimpParam *return_vals;
  498.   gint nreturn_vals;
  499.   gboolean success = TRUE;
  500.  
  501.   return_vals = gimp_run_procedure ("gimp_image_raise_layer_to_top",
  502.                     &nreturn_vals,
  503.                     GIMP_PDB_IMAGE, image_ID,
  504.                     GIMP_PDB_LAYER, layer_ID,
  505.                     GIMP_PDB_END);
  506.  
  507.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  508.  
  509.   gimp_destroy_params (return_vals, nreturn_vals);
  510.  
  511.   return success;
  512. }
  513.  
  514. /**
  515.  * gimp_image_lower_layer_to_bottom:
  516.  * @image_ID: The image.
  517.  * @layer_ID: The layer to lower to bottom.
  518.  *
  519.  * Lower the specified layer in the image's layer stack to bottom of
  520.  * stack
  521.  *
  522.  * This procedure lowers the specified layer to bottom of the existing
  523.  * layer stack. It will not move the layer if there is no layer below
  524.  * it, or the layer has no alpha channel.
  525.  *
  526.  * Returns: TRUE on success.
  527.  */
  528. gboolean
  529. gimp_image_lower_layer_to_bottom (gint32 image_ID,
  530.                   gint32 layer_ID)
  531. {
  532.   GimpParam *return_vals;
  533.   gint nreturn_vals;
  534.   gboolean success = TRUE;
  535.  
  536.   return_vals = gimp_run_procedure ("gimp_image_lower_layer_to_bottom",
  537.                     &nreturn_vals,
  538.                     GIMP_PDB_IMAGE, image_ID,
  539.                     GIMP_PDB_LAYER, layer_ID,
  540.                     GIMP_PDB_END);
  541.  
  542.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  543.  
  544.   gimp_destroy_params (return_vals, nreturn_vals);
  545.  
  546.   return success;
  547. }
  548.  
  549. /**
  550.  * gimp_image_merge_visible_layers:
  551.  * @image_ID: The image.
  552.  * @merge_type: The type of merge.
  553.  *
  554.  * Merge the visible image layers into one.
  555.  *
  556.  * This procedure combines the visible layers into a single layer using
  557.  * the specified merge type. A merge type of EXPAND_AS_NECESSARY
  558.  * expands the final layer to encompass the areas of the visible
  559.  * layers. A merge type of CLIP_TO_IMAGE clips the final layer to the
  560.  * extents of the image. A merge type of CLIP_TO_BOTTOM_LAYER clips the
  561.  * final layer to the size of the bottommost layer.
  562.  *
  563.  * Returns: The resulting layer.
  564.  */
  565. gint32
  566. gimp_image_merge_visible_layers (gint32        image_ID,
  567.                  GimpMergeType merge_type)
  568. {
  569.   GimpParam *return_vals;
  570.   gint nreturn_vals;
  571.   gint32 layer_ID = -1;
  572.  
  573.   return_vals = gimp_run_procedure ("gimp_image_merge_visible_layers",
  574.                     &nreturn_vals,
  575.                     GIMP_PDB_IMAGE, image_ID,
  576.                     GIMP_PDB_INT32, merge_type,
  577.                     GIMP_PDB_END);
  578.  
  579.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  580.     layer_ID = return_vals[1].data.d_layer;
  581.  
  582.   gimp_destroy_params (return_vals, nreturn_vals);
  583.  
  584.   return layer_ID;
  585. }
  586.  
  587. /**
  588.  * gimp_image_merge_down:
  589.  * @image_ID: The image.
  590.  * @merge_layer_ID: The layer to merge down from.
  591.  * @merge_type: The type of merge.
  592.  *
  593.  * Merge the layer passed and the first visible layer below.
  594.  *
  595.  * This procedure combines the passed layer and the first visible layer
  596.  * below it using the specified merge type. A merge type of
  597.  * EXPAND_AS_NECESSARY expands the final layer to encompass the areas
  598.  * of the visible layers. A merge type of CLIP_TO_IMAGE clips the final
  599.  * layer to the extents of the image. A merge type of
  600.  * CLIP_TO_BOTTOM_LAYER clips the final layer to the size of the
  601.  * bottommost layer.
  602.  *
  603.  * Returns: The resulting layer.
  604.  */
  605. gint32
  606. gimp_image_merge_down (gint32        image_ID,
  607.                gint32        merge_layer_ID,
  608.                GimpMergeType merge_type)
  609. {
  610.   GimpParam *return_vals;
  611.   gint nreturn_vals;
  612.   gint32 layer_ID = -1;
  613.  
  614.   return_vals = gimp_run_procedure ("gimp_image_merge_down",
  615.                     &nreturn_vals,
  616.                     GIMP_PDB_IMAGE, image_ID,
  617.                     GIMP_PDB_LAYER, merge_layer_ID,
  618.                     GIMP_PDB_INT32, merge_type,
  619.                     GIMP_PDB_END);
  620.  
  621.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  622.     layer_ID = return_vals[1].data.d_layer;
  623.  
  624.   gimp_destroy_params (return_vals, nreturn_vals);
  625.  
  626.   return layer_ID;
  627. }
  628.  
  629. /**
  630.  * gimp_image_flatten:
  631.  * @image_ID: The image.
  632.  *
  633.  * Flatten all visible layers into a single layer. Discard all
  634.  * invisible layers.
  635.  *
  636.  * This procedure combines the visible layers in a manner analogous to
  637.  * merging with the CLIP_TO_IMAGE merge type. Non-visible layers are
  638.  * discarded, and the resulting image is stripped of its alpha channel.
  639.  *
  640.  * Returns: The resulting layer.
  641.  */
  642. gint32
  643. gimp_image_flatten (gint32 image_ID)
  644. {
  645.   GimpParam *return_vals;
  646.   gint nreturn_vals;
  647.   gint32 layer_ID = -1;
  648.  
  649.   return_vals = gimp_run_procedure ("gimp_image_flatten",
  650.                     &nreturn_vals,
  651.                     GIMP_PDB_IMAGE, image_ID,
  652.                     GIMP_PDB_END);
  653.  
  654.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  655.     layer_ID = return_vals[1].data.d_layer;
  656.  
  657.   gimp_destroy_params (return_vals, nreturn_vals);
  658.  
  659.   return layer_ID;
  660. }
  661.  
  662. /**
  663.  * gimp_image_add_layer:
  664.  * @image_ID: The image.
  665.  * @layer_ID: The layer.
  666.  * @position: The layer position.
  667.  *
  668.  * Add the specified layer to the image.
  669.  *
  670.  * This procedure adds the specified layer to the gimage at the given
  671.  * position. If the position is specified as -1, then the layer is
  672.  * inserted at the top of the layer stack. If the layer to be added has
  673.  * no alpha channel, it must be added at position 0. The layer type
  674.  * must be compatible with the image base type.
  675.  *
  676.  * Returns: TRUE on success.
  677.  */
  678. gboolean
  679. gimp_image_add_layer (gint32 image_ID,
  680.               gint32 layer_ID,
  681.               gint   position)
  682. {
  683.   GimpParam *return_vals;
  684.   gint nreturn_vals;
  685.   gboolean success = TRUE;
  686.  
  687.   return_vals = gimp_run_procedure ("gimp_image_add_layer",
  688.                     &nreturn_vals,
  689.                     GIMP_PDB_IMAGE, image_ID,
  690.                     GIMP_PDB_LAYER, layer_ID,
  691.                     GIMP_PDB_INT32, position,
  692.                     GIMP_PDB_END);
  693.  
  694.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  695.  
  696.   gimp_destroy_params (return_vals, nreturn_vals);
  697.  
  698.   return success;
  699. }
  700.  
  701. /**
  702.  * gimp_image_remove_layer:
  703.  * @image_ID: The image.
  704.  * @layer_ID: The layer.
  705.  *
  706.  * Remove the specified layer from the image.
  707.  *
  708.  * This procedure removes the specified layer from the image. If the
  709.  * layer doesn't exist, an error is returned. If there are no layers
  710.  * left in the image, this call will fail. If this layer is the last
  711.  * layer remaining, the image will become empty and have no active
  712.  * layer.
  713.  *
  714.  * Returns: TRUE on success.
  715.  */
  716. gboolean
  717. gimp_image_remove_layer (gint32 image_ID,
  718.              gint32 layer_ID)
  719. {
  720.   GimpParam *return_vals;
  721.   gint nreturn_vals;
  722.   gboolean success = TRUE;
  723.  
  724.   return_vals = gimp_run_procedure ("gimp_image_remove_layer",
  725.                     &nreturn_vals,
  726.                     GIMP_PDB_IMAGE, image_ID,
  727.                     GIMP_PDB_LAYER, layer_ID,
  728.                     GIMP_PDB_END);
  729.  
  730.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  731.  
  732.   gimp_destroy_params (return_vals, nreturn_vals);
  733.  
  734.   return success;
  735. }
  736.  
  737. /**
  738.  * gimp_image_add_layer_mask:
  739.  * @image_ID: The image.
  740.  * @layer_ID: The layer to receive the mask.
  741.  * @mask_ID: The mask to add to the layer.
  742.  *
  743.  * Add a layer mask to the specified layer.
  744.  *
  745.  * This procedure adds a layer mask to the specified layer. Layer masks
  746.  * serve as an additional alpha channel for a layer. This procedure
  747.  * will fail if a number of prerequisites aren't met. The layer cannot
  748.  * already have a layer mask. The specified mask must exist and have
  749.  * the same dimensions as the layer. Both the mask and the layer must
  750.  * have been created for use with the specified image.
  751.  *
  752.  * Returns: TRUE on success.
  753.  */
  754. gboolean
  755. gimp_image_add_layer_mask (gint32 image_ID,
  756.                gint32 layer_ID,
  757.                gint32 mask_ID)
  758. {
  759.   GimpParam *return_vals;
  760.   gint nreturn_vals;
  761.   gboolean success = TRUE;
  762.  
  763.   return_vals = gimp_run_procedure ("gimp_image_add_layer_mask",
  764.                     &nreturn_vals,
  765.                     GIMP_PDB_IMAGE, image_ID,
  766.                     GIMP_PDB_LAYER, layer_ID,
  767.                     GIMP_PDB_CHANNEL, mask_ID,
  768.                     GIMP_PDB_END);
  769.  
  770.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  771.  
  772.   gimp_destroy_params (return_vals, nreturn_vals);
  773.  
  774.   return success;
  775. }
  776.  
  777. /**
  778.  * gimp_image_remove_layer_mask:
  779.  * @image_ID: The image.
  780.  * @layer_ID: The layer from which to remove mask.
  781.  * @mode: Removal mode.
  782.  *
  783.  * Remove the specified layer mask from the layer.
  784.  *
  785.  * This procedure removes the specified layer mask from the layer. If
  786.  * the mask doesn't exist, an error is returned.
  787.  *
  788.  * Returns: TRUE on success.
  789.  */
  790. gboolean
  791. gimp_image_remove_layer_mask (gint32            image_ID,
  792.                   gint32            layer_ID,
  793.                   GimpMaskApplyMode mode)
  794. {
  795.   GimpParam *return_vals;
  796.   gint nreturn_vals;
  797.   gboolean success = TRUE;
  798.  
  799.   return_vals = gimp_run_procedure ("gimp_image_remove_layer_mask",
  800.                     &nreturn_vals,
  801.                     GIMP_PDB_IMAGE, image_ID,
  802.                     GIMP_PDB_LAYER, layer_ID,
  803.                     GIMP_PDB_INT32, mode,
  804.                     GIMP_PDB_END);
  805.  
  806.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  807.  
  808.   gimp_destroy_params (return_vals, nreturn_vals);
  809.  
  810.   return success;
  811. }
  812.  
  813. /**
  814.  * gimp_image_raise_channel:
  815.  * @image_ID: The image.
  816.  * @channel_ID: The channel to raise.
  817.  *
  818.  * Raise the specified channel in the image's channel stack
  819.  *
  820.  * This procedure raises the specified channel one step in the existing
  821.  * channel stack. It will not move the channel if there is no channel
  822.  * above it.
  823.  *
  824.  * Returns: TRUE on success.
  825.  */
  826. gboolean
  827. gimp_image_raise_channel (gint32 image_ID,
  828.               gint32 channel_ID)
  829. {
  830.   GimpParam *return_vals;
  831.   gint nreturn_vals;
  832.   gboolean success = TRUE;
  833.  
  834.   return_vals = gimp_run_procedure ("gimp_image_raise_channel",
  835.                     &nreturn_vals,
  836.                     GIMP_PDB_IMAGE, image_ID,
  837.                     GIMP_PDB_CHANNEL, channel_ID,
  838.                     GIMP_PDB_END);
  839.  
  840.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  841.  
  842.   gimp_destroy_params (return_vals, nreturn_vals);
  843.  
  844.   return success;
  845. }
  846.  
  847. /**
  848.  * gimp_image_lower_channel:
  849.  * @image_ID: The image.
  850.  * @layer_ID: The layer to lower.
  851.  *
  852.  * Lower the specified layer in the image's layer stack
  853.  *
  854.  * This procedure lowers the specified layer one step in the existing
  855.  * layer stack. It will not move the layer if there is no layer below
  856.  * it, or the layer has no alpha channel.
  857.  *
  858.  * Returns: TRUE on success.
  859.  */
  860. gboolean
  861. gimp_image_lower_channel (gint32 image_ID,
  862.               gint32 layer_ID)
  863. {
  864.   GimpParam *return_vals;
  865.   gint nreturn_vals;
  866.   gboolean success = TRUE;
  867.  
  868.   return_vals = gimp_run_procedure ("gimp_image_lower_channel",
  869.                     &nreturn_vals,
  870.                     GIMP_PDB_IMAGE, image_ID,
  871.                     GIMP_PDB_LAYER, layer_ID,
  872.                     GIMP_PDB_END);
  873.  
  874.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  875.  
  876.   gimp_destroy_params (return_vals, nreturn_vals);
  877.  
  878.   return success;
  879. }
  880.  
  881. /**
  882.  * gimp_image_add_channel:
  883.  * @image_ID: The image.
  884.  * @channel_ID: The channel.
  885.  * @position: The channel position.
  886.  *
  887.  * Add the specified channel to the image.
  888.  *
  889.  * This procedure adds the specified channel to the image. The position
  890.  * channel is not currently used, so the channel is always inserted at
  891.  * the top of the channel stack.
  892.  *
  893.  * Returns: TRUE on success.
  894.  */
  895. gboolean
  896. gimp_image_add_channel (gint32 image_ID,
  897.             gint32 channel_ID,
  898.             gint   position)
  899. {
  900.   GimpParam *return_vals;
  901.   gint nreturn_vals;
  902.   gboolean success = TRUE;
  903.  
  904.   return_vals = gimp_run_procedure ("gimp_image_add_channel",
  905.                     &nreturn_vals,
  906.                     GIMP_PDB_IMAGE, image_ID,
  907.                     GIMP_PDB_CHANNEL, channel_ID,
  908.                     GIMP_PDB_INT32, position,
  909.                     GIMP_PDB_END);
  910.  
  911.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  912.  
  913.   gimp_destroy_params (return_vals, nreturn_vals);
  914.  
  915.   return success;
  916. }
  917.  
  918. /**
  919.  * gimp_image_remove_channel:
  920.  * @image_ID: The image.
  921.  * @channel_ID: The channel.
  922.  *
  923.  * Remove the specified channel from the image.
  924.  *
  925.  * This procedure removes the specified channel from the image. If the
  926.  * channel doesn't exist, an error is returned.
  927.  *
  928.  * Returns: TRUE on success.
  929.  */
  930. gboolean
  931. gimp_image_remove_channel (gint32 image_ID,
  932.                gint32 channel_ID)
  933. {
  934.   GimpParam *return_vals;
  935.   gint nreturn_vals;
  936.   gboolean success = TRUE;
  937.  
  938.   return_vals = gimp_run_procedure ("gimp_image_remove_channel",
  939.                     &nreturn_vals,
  940.                     GIMP_PDB_IMAGE, image_ID,
  941.                     GIMP_PDB_CHANNEL, channel_ID,
  942.                     GIMP_PDB_END);
  943.  
  944.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  945.  
  946.   gimp_destroy_params (return_vals, nreturn_vals);
  947.  
  948.   return success;
  949. }
  950.  
  951. /**
  952.  * gimp_image_active_drawable:
  953.  * @image_ID: The image.
  954.  *
  955.  * Get the image's active drawable
  956.  *
  957.  * This procedure returns the ID of the image's active drawable. This
  958.  * can be either a layer, a channel, or a layer mask. The active
  959.  * drawable is specified by the active image channel. If that is -1,
  960.  * then by the active image layer. If the active image layer has a
  961.  * layer mask and the layer mask is in edit mode, then the layer mask
  962.  * is the active drawable.
  963.  *
  964.  * Returns: The active drawable.
  965.  */
  966. gint32
  967. gimp_image_active_drawable (gint32 image_ID)
  968. {
  969.   GimpParam *return_vals;
  970.   gint nreturn_vals;
  971.   gint32 drawable_ID = -1;
  972.  
  973.   return_vals = gimp_run_procedure ("gimp_image_active_drawable",
  974.                     &nreturn_vals,
  975.                     GIMP_PDB_IMAGE, image_ID,
  976.                     GIMP_PDB_END);
  977.  
  978.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  979.     drawable_ID = return_vals[1].data.d_drawable;
  980.  
  981.   gimp_destroy_params (return_vals, nreturn_vals);
  982.  
  983.   return drawable_ID;
  984. }
  985.  
  986. /**
  987.  * gimp_image_base_type:
  988.  * @image_ID: The image.
  989.  *
  990.  * Get the base type of the image.
  991.  *
  992.  * This procedure returns the image's base type. Layers in the image
  993.  * must be of this subtype, but can have an optional alpha channel.
  994.  *
  995.  * Returns: The image's base type.
  996.  */
  997. GimpImageBaseType
  998. gimp_image_base_type (gint32 image_ID)
  999. {
  1000.   GimpParam *return_vals;
  1001.   gint nreturn_vals;
  1002.   GimpImageBaseType base_type = 0;
  1003.  
  1004.   return_vals = gimp_run_procedure ("gimp_image_base_type",
  1005.                     &nreturn_vals,
  1006.                     GIMP_PDB_IMAGE, image_ID,
  1007.                     GIMP_PDB_END);
  1008.  
  1009.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1010.     base_type = return_vals[1].data.d_int32;
  1011.  
  1012.   gimp_destroy_params (return_vals, nreturn_vals);
  1013.  
  1014.   return base_type;
  1015. }
  1016.  
  1017. /**
  1018.  * _gimp_image_get_cmap:
  1019.  * @image_ID: The image.
  1020.  * @num_bytes: Number of bytes in the colormap array.
  1021.  *
  1022.  * Returns the image's colormap
  1023.  *
  1024.  * This procedure returns an actual pointer to the image's colormap, as
  1025.  * well as the number of bytes contained in the colormap. The actual
  1026.  * number of colors in the transmitted colormap will be \"num_bytes\" /
  1027.  * 3. If the image is not of base type INDEXED, this pointer will be
  1028.  * NULL.
  1029.  *
  1030.  * Returns: The image's colormap.
  1031.  */
  1032. guint8 *
  1033. _gimp_image_get_cmap (gint32  image_ID,
  1034.               gint   *num_bytes)
  1035. {
  1036.   GimpParam *return_vals;
  1037.   gint nreturn_vals;
  1038.   guint8 *cmap = NULL;
  1039.  
  1040.   return_vals = gimp_run_procedure ("gimp_image_get_cmap",
  1041.                     &nreturn_vals,
  1042.                     GIMP_PDB_IMAGE, image_ID,
  1043.                     GIMP_PDB_END);
  1044.  
  1045.   *num_bytes = 0;
  1046.  
  1047.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1048.     {
  1049.       *num_bytes = return_vals[1].data.d_int32;
  1050.       cmap = g_new (guint8, *num_bytes);
  1051.       memcpy (cmap, return_vals[2].data.d_int8array,
  1052.           *num_bytes * sizeof (guint8));
  1053.     }
  1054.  
  1055.   gimp_destroy_params (return_vals, nreturn_vals);
  1056.  
  1057.   return cmap;
  1058. }
  1059.  
  1060. /**
  1061.  * _gimp_image_set_cmap:
  1062.  * @image_ID: The image.
  1063.  * @num_bytes: Number of bytes in the colormap array.
  1064.  * @cmap: The new colormap values.
  1065.  *
  1066.  * Sets the entries in the image's colormap.
  1067.  *
  1068.  * This procedure sets the entries in the specified image's colormap.
  1069.  * The number of entries is specified by the \"num_bytes\" parameter
  1070.  * and corresponds to the number of INT8 triples that must be contained
  1071.  * in the \"cmap\" array. The actual number of colors in the
  1072.  * transmitted colormap is \"num_bytes\" / 3.
  1073.  *
  1074.  * Returns: TRUE on success.
  1075.  */
  1076. gboolean
  1077. _gimp_image_set_cmap (gint32  image_ID,
  1078.               gint    num_bytes,
  1079.               guint8 *cmap)
  1080. {
  1081.   GimpParam *return_vals;
  1082.   gint nreturn_vals;
  1083.   gboolean success = TRUE;
  1084.  
  1085.   return_vals = gimp_run_procedure ("gimp_image_set_cmap",
  1086.                     &nreturn_vals,
  1087.                     GIMP_PDB_IMAGE, image_ID,
  1088.                     GIMP_PDB_INT32, num_bytes,
  1089.                     GIMP_PDB_INT8ARRAY, cmap,
  1090.                     GIMP_PDB_END);
  1091.  
  1092.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  1093.  
  1094.   gimp_destroy_params (return_vals, nreturn_vals);
  1095.  
  1096.   return success;
  1097. }
  1098.  
  1099. /**
  1100.  * gimp_image_undo_is_enabled:
  1101.  * @image_ID: The image.
  1102.  *
  1103.  * Check if the image's undo stack is enabled.
  1104.  *
  1105.  * This procedure checks if the image's undo stack is currently enabled
  1106.  * or disabled. This is useful when several plugins or scripts call
  1107.  * each other and want to check if their caller has already used
  1108.  * 'gimp_image_undo_disable' or 'gimp_image_undo_freeze'.
  1109.  *
  1110.  * Returns: True if undo is enabled for this image.
  1111.  */
  1112. gboolean
  1113. gimp_image_undo_is_enabled (gint32 image_ID)
  1114. {
  1115.   GimpParam *return_vals;
  1116.   gint nreturn_vals;
  1117.   gboolean enabled = FALSE;
  1118.  
  1119.   return_vals = gimp_run_procedure ("gimp_image_undo_is_enabled",
  1120.                     &nreturn_vals,
  1121.                     GIMP_PDB_IMAGE, image_ID,
  1122.                     GIMP_PDB_END);
  1123.  
  1124.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1125.     enabled = return_vals[1].data.d_int32;
  1126.  
  1127.   gimp_destroy_params (return_vals, nreturn_vals);
  1128.  
  1129.   return enabled;
  1130. }
  1131.  
  1132. /**
  1133.  * gimp_image_undo_enable:
  1134.  * @image_ID: The image.
  1135.  *
  1136.  * Enable the image's undo stack.
  1137.  *
  1138.  * This procedure enables the image's undo stack, allowing subsequent
  1139.  * operations to store their undo steps. This is generally called in
  1140.  * conjunction with 'gimp_image_undo_disable' to temporarily disable an
  1141.  * image undo stack.
  1142.  *
  1143.  * Returns: True if the image undo has been enabled.
  1144.  */
  1145. gboolean
  1146. gimp_image_undo_enable (gint32 image_ID)
  1147. {
  1148.   GimpParam *return_vals;
  1149.   gint nreturn_vals;
  1150.   gboolean enabled = FALSE;
  1151.  
  1152.   return_vals = gimp_run_procedure ("gimp_image_undo_enable",
  1153.                     &nreturn_vals,
  1154.                     GIMP_PDB_IMAGE, image_ID,
  1155.                     GIMP_PDB_END);
  1156.  
  1157.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1158.     enabled = return_vals[1].data.d_int32;
  1159.  
  1160.   gimp_destroy_params (return_vals, nreturn_vals);
  1161.  
  1162.   return enabled;
  1163. }
  1164.  
  1165. /**
  1166.  * gimp_image_undo_disable:
  1167.  * @image_ID: The image.
  1168.  *
  1169.  * Disable the image's undo stack.
  1170.  *
  1171.  * This procedure disables the image's undo stack, allowing subsequent
  1172.  * operations to ignore their undo steps. This is generally called in
  1173.  * conjunction with 'gimp_image_undo_enable' to temporarily disable an
  1174.  * image undo stack. This is advantageous because saving undo steps can
  1175.  * be time and memory intensive.
  1176.  *
  1177.  * Returns: True if the image undo has been disabled.
  1178.  */
  1179. gboolean
  1180. gimp_image_undo_disable (gint32 image_ID)
  1181. {
  1182.   GimpParam *return_vals;
  1183.   gint nreturn_vals;
  1184.   gboolean disabled = FALSE;
  1185.  
  1186.   return_vals = gimp_run_procedure ("gimp_image_undo_disable",
  1187.                     &nreturn_vals,
  1188.                     GIMP_PDB_IMAGE, image_ID,
  1189.                     GIMP_PDB_END);
  1190.  
  1191.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1192.     disabled = return_vals[1].data.d_int32;
  1193.  
  1194.   gimp_destroy_params (return_vals, nreturn_vals);
  1195.  
  1196.   return disabled;
  1197. }
  1198.  
  1199. /**
  1200.  * gimp_image_undo_freeze:
  1201.  * @image_ID: The image.
  1202.  *
  1203.  * Freeze the image's undo stack.
  1204.  *
  1205.  * This procedure freezes the image's undo stack, allowing subsequent
  1206.  * operations to ignore their undo steps. This is generally called in
  1207.  * conjunction with 'gimp_image_undo_thaw' to temporarily disable an
  1208.  * image undo stack. This is advantageous because saving undo steps can
  1209.  * be time and memory intensive. 'gimp_image_undo_{freeze,thaw}' and
  1210.  * 'gimp_image_undo_{disable,enable}' differ in that the former does
  1211.  * not free up all undo steps when undo is thawed, so is more suited to
  1212.  * interactive in-situ previews. It is important in this case that the
  1213.  * image is back to the same state it was frozen in before thawing,
  1214.  * else 'undo' behaviour is undefined.
  1215.  *
  1216.  * Returns: True if the image undo has been frozen.
  1217.  */
  1218. gboolean
  1219. gimp_image_undo_freeze (gint32 image_ID)
  1220. {
  1221.   GimpParam *return_vals;
  1222.   gint nreturn_vals;
  1223.   gboolean frozen = FALSE;
  1224.  
  1225.   return_vals = gimp_run_procedure ("gimp_image_undo_freeze",
  1226.                     &nreturn_vals,
  1227.                     GIMP_PDB_IMAGE, image_ID,
  1228.                     GIMP_PDB_END);
  1229.  
  1230.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1231.     frozen = return_vals[1].data.d_int32;
  1232.  
  1233.   gimp_destroy_params (return_vals, nreturn_vals);
  1234.  
  1235.   return frozen;
  1236. }
  1237.  
  1238. /**
  1239.  * gimp_image_undo_thaw:
  1240.  * @image_ID: The image.
  1241.  *
  1242.  * Thaw the image's undo stack.
  1243.  *
  1244.  * This procedure thaws the image's undo stack, allowing subsequent
  1245.  * operations to store their undo steps. This is generally called in
  1246.  * conjunction with 'gimp_image_undo_freeze' to temporarily freeze an
  1247.  * image undo stack. 'gimp_image_undo_thaw' does NOT free the undo
  1248.  * stack as 'gimp_image_undo_enable' does, so is suited for situations
  1249.  * where one wishes to leave the undo stack in the same state in which
  1250.  * one found it despite non-destructively playing with the image in the
  1251.  * meantime. An example would be in-situ plugin previews. Balancing
  1252.  * freezes and thaws and ensuring image consistancy is the
  1253.  * responsibility of the caller.
  1254.  *
  1255.  * Returns: True if the image undo has been thawed.
  1256.  */
  1257. gboolean
  1258. gimp_image_undo_thaw (gint32 image_ID)
  1259. {
  1260.   GimpParam *return_vals;
  1261.   gint nreturn_vals;
  1262.   gboolean thawed = FALSE;
  1263.  
  1264.   return_vals = gimp_run_procedure ("gimp_image_undo_thaw",
  1265.                     &nreturn_vals,
  1266.                     GIMP_PDB_IMAGE, image_ID,
  1267.                     GIMP_PDB_END);
  1268.  
  1269.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1270.     thawed = return_vals[1].data.d_int32;
  1271.  
  1272.   gimp_destroy_params (return_vals, nreturn_vals);
  1273.  
  1274.   return thawed;
  1275. }
  1276.  
  1277. /**
  1278.  * gimp_image_clean_all:
  1279.  * @image_ID: The image.
  1280.  *
  1281.  * Set the image dirty count to 0.
  1282.  *
  1283.  * This procedure sets the specified image's dirty count to 0, allowing
  1284.  * operations to occur without having a 'dirtied' image. This is
  1285.  * especially useful for creating and loading images which should not
  1286.  * initially be considered dirty, even though layers must be created,
  1287.  * filled, and installed in the image.
  1288.  *
  1289.  * Returns: TRUE on success.
  1290.  */
  1291. gboolean
  1292. gimp_image_clean_all (gint32 image_ID)
  1293. {
  1294.   GimpParam *return_vals;
  1295.   gint nreturn_vals;
  1296.   gboolean success = TRUE;
  1297.  
  1298.   return_vals = gimp_run_procedure ("gimp_image_clean_all",
  1299.                     &nreturn_vals,
  1300.                     GIMP_PDB_IMAGE, image_ID,
  1301.                     GIMP_PDB_END);
  1302.  
  1303.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  1304.  
  1305.   gimp_destroy_params (return_vals, nreturn_vals);
  1306.  
  1307.   return success;
  1308. }
  1309.  
  1310. /**
  1311.  * gimp_image_floating_selection:
  1312.  * @image_ID: The image.
  1313.  *
  1314.  * Return the floating selection of the image.
  1315.  *
  1316.  * This procedure returns the image's floating_sel, if it exists. If it
  1317.  * doesn't exist, -1 is returned as the layer ID.
  1318.  *
  1319.  * Returns: The image's floating selection.
  1320.  */
  1321. gint32
  1322. gimp_image_floating_selection (gint32 image_ID)
  1323. {
  1324.   GimpParam *return_vals;
  1325.   gint nreturn_vals;
  1326.   gint32 floating_sel_ID = -1;
  1327.  
  1328.   return_vals = gimp_run_procedure ("gimp_image_floating_selection",
  1329.                     &nreturn_vals,
  1330.                     GIMP_PDB_IMAGE, image_ID,
  1331.                     GIMP_PDB_END);
  1332.  
  1333.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1334.     floating_sel_ID = return_vals[1].data.d_layer;
  1335.  
  1336.   gimp_destroy_params (return_vals, nreturn_vals);
  1337.  
  1338.   return floating_sel_ID;
  1339. }
  1340.  
  1341. /**
  1342.  * gimp_image_floating_sel_attached_to:
  1343.  * @image_ID: The image.
  1344.  *
  1345.  * Return the drawable the floating selection is attached to.
  1346.  *
  1347.  * This procedure returns the drawable the image's floating selection
  1348.  * is attached to, if it exists. If it doesn't exist, -1 is returned as
  1349.  * the drawable ID.
  1350.  *
  1351.  * Returns: The drawable the floating selection is attached to.
  1352.  */
  1353. gint32
  1354. gimp_image_floating_sel_attached_to (gint32 image_ID)
  1355. {
  1356.   GimpParam *return_vals;
  1357.   gint nreturn_vals;
  1358.   gint32 drawable_ID = -1;
  1359.  
  1360.   return_vals = gimp_run_procedure ("gimp_image_floating_sel_attached_to",
  1361.                     &nreturn_vals,
  1362.                     GIMP_PDB_IMAGE, image_ID,
  1363.                     GIMP_PDB_END);
  1364.  
  1365.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1366.     drawable_ID = return_vals[1].data.d_drawable;
  1367.  
  1368.   gimp_destroy_params (return_vals, nreturn_vals);
  1369.  
  1370.   return drawable_ID;
  1371. }
  1372.  
  1373. /**
  1374.  * _gimp_image_thumbnail:
  1375.  * @image_ID: The image.
  1376.  * @width: The thumbnail width.
  1377.  * @height: The thumbnail height.
  1378.  * @ret_width: The previews width.
  1379.  * @ret_height: The previews height.
  1380.  * @bpp: The previews bpp.
  1381.  * @thumbnail_data_count: The number of bytes in thumbnail data.
  1382.  * @thumbnail_data: The thumbnail data.
  1383.  *
  1384.  * Get a thumbnail of an image.
  1385.  *
  1386.  * This function gets data from which a thumbnail of an image preview
  1387.  * can be created. Maximum x or y dimension is 128 pixels. The pixels
  1388.  * are returned in the RGB[A] format. The bpp return value gives the
  1389.  * number of bits per pixel in the image. If the image has an alpha
  1390.  * channel, it is also returned.
  1391.  *
  1392.  * Returns: TRUE on success.
  1393.  */
  1394. gboolean
  1395. _gimp_image_thumbnail (gint32   image_ID,
  1396.                gint     width,
  1397.                gint     height,
  1398.                gint    *ret_width,
  1399.                gint    *ret_height,
  1400.                gint    *bpp,
  1401.                gint    *thumbnail_data_count,
  1402.                guint8 **thumbnail_data)
  1403. {
  1404.   GimpParam *return_vals;
  1405.   gint nreturn_vals;
  1406.   gboolean success = TRUE;
  1407.  
  1408.   return_vals = gimp_run_procedure ("gimp_image_thumbnail",
  1409.                     &nreturn_vals,
  1410.                     GIMP_PDB_IMAGE, image_ID,
  1411.                     GIMP_PDB_INT32, width,
  1412.                     GIMP_PDB_INT32, height,
  1413.                     GIMP_PDB_END);
  1414.  
  1415.   *ret_width = 0;
  1416.   *ret_height = 0;
  1417.   *bpp = 0;
  1418.   *thumbnail_data_count = 0;
  1419.   *thumbnail_data = NULL;
  1420.  
  1421.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  1422.  
  1423.   if (success)
  1424.     {
  1425.       *ret_width = return_vals[1].data.d_int32;
  1426.       *ret_height = return_vals[2].data.d_int32;
  1427.       *bpp = return_vals[3].data.d_int32;
  1428.       *thumbnail_data_count = return_vals[4].data.d_int32;
  1429.       *thumbnail_data = g_new (guint8, *thumbnail_data_count);
  1430.       memcpy (*thumbnail_data, return_vals[5].data.d_int8array,
  1431.           *thumbnail_data_count * sizeof (guint8));
  1432.     }
  1433.  
  1434.   gimp_destroy_params (return_vals, nreturn_vals);
  1435.  
  1436.   return success;
  1437. }
  1438.  
  1439. /**
  1440.  * gimp_image_set_tattoo_state:
  1441.  * @image_ID: The image.
  1442.  * @tattoo: The new tattoo state of the image.
  1443.  *
  1444.  * Set the tattoo state associated with the image.
  1445.  *
  1446.  * This procedure sets the tattoo state of the image. Use only by
  1447.  * save/load plugins that wish to preserve an images tattoo state.
  1448.  * Using this function at other times will produce unexpected results.
  1449.  * A full check of uniqueness of states in layers, channels and paths
  1450.  * will be performed by this procedure and a execution failure will be
  1451.  * returned if this fails. A failure will also be returned if the new
  1452.  * tattoo state value is less than the maximum tattoo value from all of
  1453.  * the tattoos from the paths,layers and channels. After the image data
  1454.  * has been loaded and all the tattoos have been set then this is the
  1455.  * last procedure that should be called. If effectively does a status
  1456.  * check on the tattoo values that have been set to make sure that all
  1457.  * is OK.
  1458.  *
  1459.  * Returns: TRUE on success.
  1460.  */
  1461. gboolean
  1462. gimp_image_set_tattoo_state (gint32 image_ID,
  1463.                  gint   tattoo)
  1464. {
  1465.   GimpParam *return_vals;
  1466.   gint nreturn_vals;
  1467.   gboolean success = TRUE;
  1468.  
  1469.   return_vals = gimp_run_procedure ("gimp_image_set_tattoo_state",
  1470.                     &nreturn_vals,
  1471.                     GIMP_PDB_IMAGE, image_ID,
  1472.                     GIMP_PDB_INT32, tattoo,
  1473.                     GIMP_PDB_END);
  1474.  
  1475.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  1476.  
  1477.   gimp_destroy_params (return_vals, nreturn_vals);
  1478.  
  1479.   return success;
  1480. }
  1481.  
  1482. /**
  1483.  * gimp_image_get_tattoo_state:
  1484.  * @image_ID: The image.
  1485.  *
  1486.  * Returns the tattoo state associated with the image.
  1487.  *
  1488.  * This procedure returns the tattoo state of the image. Use only by
  1489.  * save/load plugins that wish to preserve an images tattoo state.
  1490.  * Using this function at other times will produce unexpected results.
  1491.  *
  1492.  * Returns: The tattoo state associated with the image.
  1493.  */
  1494. gint
  1495. gimp_image_get_tattoo_state (gint32 image_ID)
  1496. {
  1497.   GimpParam *return_vals;
  1498.   gint nreturn_vals;
  1499.   gint tattoo = 0;
  1500.  
  1501.   return_vals = gimp_run_procedure ("gimp_image_get_tattoo_state",
  1502.                     &nreturn_vals,
  1503.                     GIMP_PDB_IMAGE, image_ID,
  1504.                     GIMP_PDB_END);
  1505.  
  1506.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1507.     tattoo = return_vals[1].data.d_int32;
  1508.  
  1509.   gimp_destroy_params (return_vals, nreturn_vals);
  1510.  
  1511.   return tattoo;
  1512. }
  1513.  
  1514. /**
  1515.  * gimp_image_width:
  1516.  * @image_ID: The image.
  1517.  *
  1518.  * Return the width of the image
  1519.  *
  1520.  * This procedure returns the image's width. This value is independent
  1521.  * of any of the layers in this image. This is the \"canvas\" width.
  1522.  *
  1523.  * Returns: The image's width.
  1524.  */
  1525. gint
  1526. gimp_image_width (gint32 image_ID)
  1527. {
  1528.   GimpParam *return_vals;
  1529.   gint nreturn_vals;
  1530.   gint width = 0;
  1531.  
  1532.   return_vals = gimp_run_procedure ("gimp_image_width",
  1533.                     &nreturn_vals,
  1534.                     GIMP_PDB_IMAGE, image_ID,
  1535.                     GIMP_PDB_END);
  1536.  
  1537.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1538.     width = return_vals[1].data.d_int32;
  1539.  
  1540.   gimp_destroy_params (return_vals, nreturn_vals);
  1541.  
  1542.   return width;
  1543. }
  1544.  
  1545. /**
  1546.  * gimp_image_height:
  1547.  * @image_ID: The image.
  1548.  *
  1549.  * Return the height of the image
  1550.  *
  1551.  * This procedure returns the image's width. This value is independent
  1552.  * of any of the layers in this image. This is the \"canvas\" height.
  1553.  *
  1554.  * Returns: The image's height.
  1555.  */
  1556. gint
  1557. gimp_image_height (gint32 image_ID)
  1558. {
  1559.   GimpParam *return_vals;
  1560.   gint nreturn_vals;
  1561.   gint height = 0;
  1562.  
  1563.   return_vals = gimp_run_procedure ("gimp_image_height",
  1564.                     &nreturn_vals,
  1565.                     GIMP_PDB_IMAGE, image_ID,
  1566.                     GIMP_PDB_END);
  1567.  
  1568.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1569.     height = return_vals[1].data.d_int32;
  1570.  
  1571.   gimp_destroy_params (return_vals, nreturn_vals);
  1572.  
  1573.   return height;
  1574. }
  1575.  
  1576. /**
  1577.  * gimp_image_get_active_layer:
  1578.  * @image_ID: The image.
  1579.  *
  1580.  * Returns the specified image's active layer.
  1581.  *
  1582.  * If there is an active layer, its ID will be returned, otherwise, -1.
  1583.  * If a channel is currently active, then no layer will be. If a layer
  1584.  * mask is active, then this will return the associated layer.
  1585.  *
  1586.  * Returns: The active layer.
  1587.  */
  1588. gint32
  1589. gimp_image_get_active_layer (gint32 image_ID)
  1590. {
  1591.   GimpParam *return_vals;
  1592.   gint nreturn_vals;
  1593.   gint32 active_layer_ID = -1;
  1594.  
  1595.   return_vals = gimp_run_procedure ("gimp_image_get_active_layer",
  1596.                     &nreturn_vals,
  1597.                     GIMP_PDB_IMAGE, image_ID,
  1598.                     GIMP_PDB_END);
  1599.  
  1600.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1601.     active_layer_ID = return_vals[1].data.d_layer;
  1602.  
  1603.   gimp_destroy_params (return_vals, nreturn_vals);
  1604.  
  1605.   return active_layer_ID;
  1606. }
  1607.  
  1608. /**
  1609.  * gimp_image_set_active_layer:
  1610.  * @image_ID: The image.
  1611.  * @active_layer_ID: The new image active layer.
  1612.  *
  1613.  * Sets the specified image's active layer.
  1614.  *
  1615.  * If the layer exists, it is set as the active layer in the image. Any
  1616.  * previous active layer or channel is set to inactive. An exception is
  1617.  * a previously existing floating selection, in which case this
  1618.  * procedure will return an execution error.
  1619.  *
  1620.  * Returns: TRUE on success.
  1621.  */
  1622. gboolean
  1623. gimp_image_set_active_layer (gint32 image_ID,
  1624.                  gint32 active_layer_ID)
  1625. {
  1626.   GimpParam *return_vals;
  1627.   gint nreturn_vals;
  1628.   gboolean success = TRUE;
  1629.  
  1630.   return_vals = gimp_run_procedure ("gimp_image_set_active_layer",
  1631.                     &nreturn_vals,
  1632.                     GIMP_PDB_IMAGE, image_ID,
  1633.                     GIMP_PDB_LAYER, active_layer_ID,
  1634.                     GIMP_PDB_END);
  1635.  
  1636.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  1637.  
  1638.   gimp_destroy_params (return_vals, nreturn_vals);
  1639.  
  1640.   return success;
  1641. }
  1642.  
  1643. /**
  1644.  * gimp_image_get_active_channel:
  1645.  * @image_ID: The image.
  1646.  *
  1647.  * Returns the specified image's active channel.
  1648.  *
  1649.  * If there is an active channel, this will return the channel ID,
  1650.  * otherwise, -1.
  1651.  *
  1652.  * Returns: The active channel.
  1653.  */
  1654. gint32
  1655. gimp_image_get_active_channel (gint32 image_ID)
  1656. {
  1657.   GimpParam *return_vals;
  1658.   gint nreturn_vals;
  1659.   gint32 active_channel_ID = -1;
  1660.  
  1661.   return_vals = gimp_run_procedure ("gimp_image_get_active_channel",
  1662.                     &nreturn_vals,
  1663.                     GIMP_PDB_IMAGE, image_ID,
  1664.                     GIMP_PDB_END);
  1665.  
  1666.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1667.     active_channel_ID = return_vals[1].data.d_channel;
  1668.  
  1669.   gimp_destroy_params (return_vals, nreturn_vals);
  1670.  
  1671.   return active_channel_ID;
  1672. }
  1673.  
  1674. /**
  1675.  * gimp_image_set_active_channel:
  1676.  * @image_ID: The image.
  1677.  * @active_channel_ID: The new image active channel.
  1678.  *
  1679.  * Sets the specified image's active channel.
  1680.  *
  1681.  * If the channel exists, it is set as the active channel in the image.
  1682.  * Any previous active channel or channel is set to inactive. An
  1683.  * exception is a previously existing floating selection, in which case
  1684.  * this procedure will return an execution error.
  1685.  *
  1686.  * Returns: TRUE on success.
  1687.  */
  1688. gboolean
  1689. gimp_image_set_active_channel (gint32 image_ID,
  1690.                    gint32 active_channel_ID)
  1691. {
  1692.   GimpParam *return_vals;
  1693.   gint nreturn_vals;
  1694.   gboolean success = TRUE;
  1695.  
  1696.   return_vals = gimp_run_procedure ("gimp_image_set_active_channel",
  1697.                     &nreturn_vals,
  1698.                     GIMP_PDB_IMAGE, image_ID,
  1699.                     GIMP_PDB_CHANNEL, active_channel_ID,
  1700.                     GIMP_PDB_END);
  1701.  
  1702.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  1703.  
  1704.   gimp_destroy_params (return_vals, nreturn_vals);
  1705.  
  1706.   return success;
  1707. }
  1708.  
  1709. /**
  1710.  * gimp_image_get_selection:
  1711.  * @image_ID: The image.
  1712.  *
  1713.  * Returns the specified image's selection.
  1714.  *
  1715.  * This will always return a valid ID for a selection -- which is
  1716.  * represented as a channel internally.
  1717.  *
  1718.  * Returns: The selection channel.
  1719.  */
  1720. gint32
  1721. gimp_image_get_selection (gint32 image_ID)
  1722. {
  1723.   GimpParam *return_vals;
  1724.   gint nreturn_vals;
  1725.   gint32 selection_ID = -1;
  1726.  
  1727.   return_vals = gimp_run_procedure ("gimp_image_get_selection",
  1728.                     &nreturn_vals,
  1729.                     GIMP_PDB_IMAGE, image_ID,
  1730.                     GIMP_PDB_END);
  1731.  
  1732.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1733.     selection_ID = return_vals[1].data.d_selection;
  1734.  
  1735.   gimp_destroy_params (return_vals, nreturn_vals);
  1736.  
  1737.   return selection_ID;
  1738. }
  1739.  
  1740. /**
  1741.  * gimp_image_get_component_active:
  1742.  * @image_ID: The image.
  1743.  * @component: The image component.
  1744.  *
  1745.  * Returns if the specified image's image component is active.
  1746.  *
  1747.  * This procedure returns if the specified image's image component
  1748.  * (i.e. Red, Green, Blue intensity channels in an RGB image) is active
  1749.  * or inactive -- whether or not it can be modified. If the specified
  1750.  * component is not valid for the image type, an error is returned.
  1751.  *
  1752.  * Returns: Component is active.
  1753.  */
  1754. gboolean
  1755. gimp_image_get_component_active (gint32          image_ID,
  1756.                  GimpChannelType component)
  1757. {
  1758.   GimpParam *return_vals;
  1759.   gint nreturn_vals;
  1760.   gboolean active = FALSE;
  1761.  
  1762.   return_vals = gimp_run_procedure ("gimp_image_get_component_active",
  1763.                     &nreturn_vals,
  1764.                     GIMP_PDB_IMAGE, image_ID,
  1765.                     GIMP_PDB_INT32, component,
  1766.                     GIMP_PDB_END);
  1767.  
  1768.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1769.     active = return_vals[1].data.d_int32;
  1770.  
  1771.   gimp_destroy_params (return_vals, nreturn_vals);
  1772.  
  1773.   return active;
  1774. }
  1775.  
  1776. /**
  1777.  * gimp_image_set_component_active:
  1778.  * @image_ID: The image.
  1779.  * @component: The image component.
  1780.  * @active: Component is active.
  1781.  *
  1782.  * Sets if the specified image's image component is active.
  1783.  *
  1784.  * This procedure sets if the specified image's image component (i.e.
  1785.  * Red, Green, Blue intensity channels in an RGB image) is active or
  1786.  * inactive -- whether or not it can be modified. If the specified
  1787.  * component is not valid for the image type, an error is returned.
  1788.  *
  1789.  * Returns: TRUE on success.
  1790.  */
  1791. gboolean
  1792. gimp_image_set_component_active (gint32          image_ID,
  1793.                  GimpChannelType component,
  1794.                  gboolean        active)
  1795. {
  1796.   GimpParam *return_vals;
  1797.   gint nreturn_vals;
  1798.   gboolean success = TRUE;
  1799.  
  1800.   return_vals = gimp_run_procedure ("gimp_image_set_component_active",
  1801.                     &nreturn_vals,
  1802.                     GIMP_PDB_IMAGE, image_ID,
  1803.                     GIMP_PDB_INT32, component,
  1804.                     GIMP_PDB_INT32, active,
  1805.                     GIMP_PDB_END);
  1806.  
  1807.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  1808.  
  1809.   gimp_destroy_params (return_vals, nreturn_vals);
  1810.  
  1811.   return success;
  1812. }
  1813.  
  1814. /**
  1815.  * gimp_image_get_component_visible:
  1816.  * @image_ID: The image.
  1817.  * @component: The image component.
  1818.  *
  1819.  * Returns if the specified image's image component is visible.
  1820.  *
  1821.  * This procedure returns if the specified image's image component
  1822.  * (i.e. Red, Green, Blue intensity channels in an RGB image) is
  1823.  * visible or invisible -- whether or not it can be seen. If the
  1824.  * specified component is not valid for the image type, an error is
  1825.  * returned.
  1826.  *
  1827.  * Returns: Component is visible.
  1828.  */
  1829. gboolean
  1830. gimp_image_get_component_visible (gint32          image_ID,
  1831.                   GimpChannelType component)
  1832. {
  1833.   GimpParam *return_vals;
  1834.   gint nreturn_vals;
  1835.   gboolean visible = FALSE;
  1836.  
  1837.   return_vals = gimp_run_procedure ("gimp_image_get_component_visible",
  1838.                     &nreturn_vals,
  1839.                     GIMP_PDB_IMAGE, image_ID,
  1840.                     GIMP_PDB_INT32, component,
  1841.                     GIMP_PDB_END);
  1842.  
  1843.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1844.     visible = return_vals[1].data.d_int32;
  1845.  
  1846.   gimp_destroy_params (return_vals, nreturn_vals);
  1847.  
  1848.   return visible;
  1849. }
  1850.  
  1851. /**
  1852.  * gimp_image_set_component_visible:
  1853.  * @image_ID: The image.
  1854.  * @component: The image component.
  1855.  * @visible: Component is visible.
  1856.  *
  1857.  * Sets if the specified image's image component is visible.
  1858.  *
  1859.  * This procedure sets if the specified image's image component (i.e.
  1860.  * Red, Green, Blue intensity channels in an RGB image) is visible or
  1861.  * invisible -- whether or not it can be seen. If the specified
  1862.  * component is not valid for the image type, an error is returned.
  1863.  *
  1864.  * Returns: TRUE on success.
  1865.  */
  1866. gboolean
  1867. gimp_image_set_component_visible (gint32          image_ID,
  1868.                   GimpChannelType component,
  1869.                   gboolean        visible)
  1870. {
  1871.   GimpParam *return_vals;
  1872.   gint nreturn_vals;
  1873.   gboolean success = TRUE;
  1874.  
  1875.   return_vals = gimp_run_procedure ("gimp_image_set_component_visible",
  1876.                     &nreturn_vals,
  1877.                     GIMP_PDB_IMAGE, image_ID,
  1878.                     GIMP_PDB_INT32, component,
  1879.                     GIMP_PDB_INT32, visible,
  1880.                     GIMP_PDB_END);
  1881.  
  1882.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  1883.  
  1884.   gimp_destroy_params (return_vals, nreturn_vals);
  1885.  
  1886.   return success;
  1887. }
  1888.  
  1889. /**
  1890.  * gimp_image_get_filename:
  1891.  * @image_ID: The image.
  1892.  *
  1893.  * Returns the specified image's filename.
  1894.  *
  1895.  * This procedure returns the specified image's filename -- if it was
  1896.  * loaded or has since been saved. Otherwise, returns NULL.
  1897.  *
  1898.  * Returns: The filename.
  1899.  */
  1900. gchar *
  1901. gimp_image_get_filename (gint32 image_ID)
  1902. {
  1903.   GimpParam *return_vals;
  1904.   gint nreturn_vals;
  1905.   gchar *filename = NULL;
  1906.  
  1907.   return_vals = gimp_run_procedure ("gimp_image_get_filename",
  1908.                     &nreturn_vals,
  1909.                     GIMP_PDB_IMAGE, image_ID,
  1910.                     GIMP_PDB_END);
  1911.  
  1912.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1913.     filename = g_strdup (return_vals[1].data.d_string);
  1914.  
  1915.   gimp_destroy_params (return_vals, nreturn_vals);
  1916.  
  1917.   return filename;
  1918. }
  1919.  
  1920. /**
  1921.  * gimp_image_set_filename:
  1922.  * @image_ID: The image.
  1923.  * @filename: The new image filename.
  1924.  *
  1925.  * Sets the specified image's filename.
  1926.  *
  1927.  * This procedure sets the specified image's filename.
  1928.  *
  1929.  * Returns: TRUE on success.
  1930.  */
  1931. gboolean
  1932. gimp_image_set_filename (gint32  image_ID,
  1933.              gchar  *filename)
  1934. {
  1935.   GimpParam *return_vals;
  1936.   gint nreturn_vals;
  1937.   gboolean success = TRUE;
  1938.  
  1939.   return_vals = gimp_run_procedure ("gimp_image_set_filename",
  1940.                     &nreturn_vals,
  1941.                     GIMP_PDB_IMAGE, image_ID,
  1942.                     GIMP_PDB_STRING, filename,
  1943.                     GIMP_PDB_END);
  1944.  
  1945.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  1946.  
  1947.   gimp_destroy_params (return_vals, nreturn_vals);
  1948.  
  1949.   return success;
  1950. }
  1951.  
  1952. /**
  1953.  * gimp_image_get_resolution:
  1954.  * @image_ID: The image.
  1955.  * @xresolution: The resolutionin the x-axis, in dots per inch.
  1956.  * @yresolution: The resolutionin the y-axis, in dots per inch.
  1957.  *
  1958.  * Returns the specified image's resolution.
  1959.  *
  1960.  * This procedure returns the specified image's resolution in dots per
  1961.  * inch. This value is independent of any of the layers in this image.
  1962.  *
  1963.  * Returns: TRUE on success.
  1964.  */
  1965. gboolean
  1966. gimp_image_get_resolution (gint32   image_ID,
  1967.                gdouble *xresolution,
  1968.                gdouble *yresolution)
  1969. {
  1970.   GimpParam *return_vals;
  1971.   gint nreturn_vals;
  1972.   gboolean success = TRUE;
  1973.  
  1974.   return_vals = gimp_run_procedure ("gimp_image_get_resolution",
  1975.                     &nreturn_vals,
  1976.                     GIMP_PDB_IMAGE, image_ID,
  1977.                     GIMP_PDB_END);
  1978.  
  1979.   *xresolution = 0.0;
  1980.   *yresolution = 0.0;
  1981.  
  1982.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  1983.  
  1984.   if (success)
  1985.     {
  1986.       *xresolution = return_vals[1].data.d_float;
  1987.       *yresolution = return_vals[2].data.d_float;
  1988.     }
  1989.  
  1990.   gimp_destroy_params (return_vals, nreturn_vals);
  1991.  
  1992.   return success;
  1993. }
  1994.  
  1995. /**
  1996.  * gimp_image_set_resolution:
  1997.  * @image_ID: The image.
  1998.  * @xresolution: The new image resolution in the x-axis, in dots per inch.
  1999.  * @yresolution: The new image resolution in the y-axis, in dots per inch.
  2000.  *
  2001.  * Sets the specified image's resolution.
  2002.  *
  2003.  * This procedure sets the specified image's resolution in dots per
  2004.  * inch. This value is independent of any of the layers in this image.
  2005.  * No scaling or resizing is performed.
  2006.  *
  2007.  * Returns: TRUE on success.
  2008.  */
  2009. gboolean
  2010. gimp_image_set_resolution (gint32  image_ID,
  2011.                gdouble xresolution,
  2012.                gdouble yresolution)
  2013. {
  2014.   GimpParam *return_vals;
  2015.   gint nreturn_vals;
  2016.   gboolean success = TRUE;
  2017.  
  2018.   return_vals = gimp_run_procedure ("gimp_image_set_resolution",
  2019.                     &nreturn_vals,
  2020.                     GIMP_PDB_IMAGE, image_ID,
  2021.                     GIMP_PDB_FLOAT, xresolution,
  2022.                     GIMP_PDB_FLOAT, yresolution,
  2023.                     GIMP_PDB_END);
  2024.  
  2025.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  2026.  
  2027.   gimp_destroy_params (return_vals, nreturn_vals);
  2028.  
  2029.   return success;
  2030. }
  2031.  
  2032. /**
  2033.  * gimp_image_get_unit:
  2034.  * @image_ID: The image.
  2035.  *
  2036.  * Returns the specified image's unit.
  2037.  *
  2038.  * This procedure returns the specified image's unit. This value is
  2039.  * independent of any of the layers in this image. See the gimp_unit_*
  2040.  * procedure definitions for the valid range of unit IDs and a
  2041.  * description of the unit system.
  2042.  *
  2043.  * Returns: The unit.
  2044.  */
  2045. GimpUnit
  2046. gimp_image_get_unit (gint32 image_ID)
  2047. {
  2048.   GimpParam *return_vals;
  2049.   gint nreturn_vals;
  2050.   GimpUnit unit = 0;
  2051.  
  2052.   return_vals = gimp_run_procedure ("gimp_image_get_unit",
  2053.                     &nreturn_vals,
  2054.                     GIMP_PDB_IMAGE, image_ID,
  2055.                     GIMP_PDB_END);
  2056.  
  2057.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  2058.     unit = return_vals[1].data.d_unit;
  2059.  
  2060.   gimp_destroy_params (return_vals, nreturn_vals);
  2061.  
  2062.   return unit;
  2063. }
  2064.  
  2065. /**
  2066.  * gimp_image_set_unit:
  2067.  * @image_ID: The image.
  2068.  * @unit: The new image unit.
  2069.  *
  2070.  * Sets the specified image's unit.
  2071.  *
  2072.  * This procedure sets the specified image's unit. No scaling or
  2073.  * resizing is performed. This value is independent of any of the
  2074.  * layers in this image. See the gimp_unit_* procedure definitions for
  2075.  * the valid range of unit IDs and a description of the unit system.
  2076.  *
  2077.  * Returns: TRUE on success.
  2078.  */
  2079. gboolean
  2080. gimp_image_set_unit (gint32   image_ID,
  2081.              GimpUnit unit)
  2082. {
  2083.   GimpParam *return_vals;
  2084.   gint nreturn_vals;
  2085.   gboolean success = TRUE;
  2086.  
  2087.   return_vals = gimp_run_procedure ("gimp_image_set_unit",
  2088.                     &nreturn_vals,
  2089.                     GIMP_PDB_IMAGE, image_ID,
  2090.                     GIMP_PDB_INT32, unit,
  2091.                     GIMP_PDB_END);
  2092.  
  2093.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  2094.  
  2095.   gimp_destroy_params (return_vals, nreturn_vals);
  2096.  
  2097.   return success;
  2098. }
  2099.  
  2100. /**
  2101.  * gimp_image_get_layer_by_tattoo:
  2102.  * @image_ID: The image.
  2103.  * @tattoo: The tattoo of the layer to find.
  2104.  *
  2105.  * Find a layer with a given tattoo in an image.
  2106.  *
  2107.  * This procedure returns the layer with the given tattoo in the
  2108.  * specified image.
  2109.  *
  2110.  * Returns: The layer with the specified tattoo.
  2111.  */
  2112. gint32
  2113. gimp_image_get_layer_by_tattoo (gint32 image_ID,
  2114.                 gint   tattoo)
  2115. {
  2116.   GimpParam *return_vals;
  2117.   gint nreturn_vals;
  2118.   gint32 layer_ID = -1;
  2119.  
  2120.   return_vals = gimp_run_procedure ("gimp_image_get_layer_by_tattoo",
  2121.                     &nreturn_vals,
  2122.                     GIMP_PDB_IMAGE, image_ID,
  2123.                     GIMP_PDB_INT32, tattoo,
  2124.                     GIMP_PDB_END);
  2125.  
  2126.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  2127.     layer_ID = return_vals[1].data.d_layer;
  2128.  
  2129.   gimp_destroy_params (return_vals, nreturn_vals);
  2130.  
  2131.   return layer_ID;
  2132. }
  2133.  
  2134. /**
  2135.  * gimp_image_get_channel_by_tattoo:
  2136.  * @image_ID: The image.
  2137.  * @tattoo: The tattoo of the channel to find.
  2138.  *
  2139.  * Find a channel with a given tattoo in an image.
  2140.  *
  2141.  * This procedure returns the channel with the given tattoo in the
  2142.  * specified image.
  2143.  *
  2144.  * Returns: The channel with the specified tattoo.
  2145.  */
  2146. gint32
  2147. gimp_image_get_channel_by_tattoo (gint32 image_ID,
  2148.                   gint   tattoo)
  2149. {
  2150.   GimpParam *return_vals;
  2151.   gint nreturn_vals;
  2152.   gint32 channel_ID = -1;
  2153.  
  2154.   return_vals = gimp_run_procedure ("gimp_image_get_channel_by_tattoo",
  2155.                     &nreturn_vals,
  2156.                     GIMP_PDB_IMAGE, image_ID,
  2157.                     GIMP_PDB_INT32, tattoo,
  2158.                     GIMP_PDB_END);
  2159.  
  2160.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  2161.     channel_ID = return_vals[1].data.d_channel;
  2162.  
  2163.   gimp_destroy_params (return_vals, nreturn_vals);
  2164.  
  2165.   return channel_ID;
  2166. }
  2167.