gimpgradient: GIMP Library Reference Manual

+ + +

gimpgradient

gimpgradient — Functions operating on a single gradient.

Functions

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+gchar * +	+gimp_gradient_new () +
+gchar * +	+gimp_gradient_duplicate () +
+gchar * +	+gimp_gradient_rename () +
+gboolean +	+gimp_gradient_delete () +
+gboolean +	+gimp_gradient_is_editable () +
+gboolean +	+gimp_gradient_get_uniform_samples () +
+gboolean +	+gimp_gradient_get_custom_samples () +
+gint +	+gimp_gradient_get_number_of_segments () +
+gboolean +	+gimp_gradient_segment_get_left_color () +
+gboolean +	+gimp_gradient_segment_set_left_color () +
+gboolean +	+gimp_gradient_segment_get_right_color () +
+gboolean +	+gimp_gradient_segment_set_right_color () +
+gboolean +	+gimp_gradient_segment_get_left_pos () +
+gboolean +	+gimp_gradient_segment_set_left_pos () +
+gboolean +	+gimp_gradient_segment_get_middle_pos () +
+gboolean +	+gimp_gradient_segment_set_middle_pos () +
+gboolean +	+gimp_gradient_segment_get_right_pos () +
+gboolean +	+gimp_gradient_segment_set_right_pos () +
+gboolean +	+gimp_gradient_segment_get_blending_function () +
+gboolean +	+gimp_gradient_segment_get_coloring_type () +
+gboolean +	+gimp_gradient_segment_range_set_blending_function () +
+gboolean +	+gimp_gradient_segment_range_set_coloring_type () +
+gboolean +	+gimp_gradient_segment_range_flip () +
+gboolean +	+gimp_gradient_segment_range_replicate () +
+gboolean +	+gimp_gradient_segment_range_split_midpoint () +
+gboolean +	+gimp_gradient_segment_range_split_uniform () +
+gboolean +	+gimp_gradient_segment_range_delete () +
+gboolean +	+gimp_gradient_segment_range_redistribute_handles () +
+gboolean +	+gimp_gradient_segment_range_blend_colors () +
+gboolean +	+gimp_gradient_segment_range_blend_opacity () +
+gdouble +	+gimp_gradient_segment_range_move () +

Description

Functions operating on a single gradient.

Functions

gimp_gradient_new ()

gchar *
+gimp_gradient_new (const gchar *name);

Creates a new gradient

This procedure creates a new, uninitialized gradient

Parameters

+++++ + + + + + +

name

The requested name of the new gradient.

Returns

The actual new gradient name.

Since: 2.2

gimp_gradient_duplicate ()

gchar *
+gimp_gradient_duplicate (const gchar *name);

Duplicates a gradient

This procedure creates an identical gradient by a different name

Parameters

+++++ + + + + + +

name

The gradient name.

Returns

The name of the gradient's copy.

Since: 2.2

gimp_gradient_rename ()

gchar *
+gimp_gradient_rename (const gchar *name,
+                      const gchar *new_name);

Rename a gradient

This procedure renames a gradient

Parameters

+++++ + + + + + + + + + + + + +

name	The gradient name.
new_name	The new name of the gradient.

Returns

The actual new name of the gradient.

Since: 2.2

gimp_gradient_delete ()

gboolean
+gimp_gradient_delete (const gchar *name);

Deletes a gradient

This procedure deletes a gradient

Parameters

+++++ + + + + + +

name

The gradient name.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_is_editable ()

gboolean
+gimp_gradient_is_editable (const gchar *name);

Tests if gradient can be edited

Returns TRUE if you have permission to change the gradient

Parameters

+++++ + + + + + +

name

The gradient name.

Returns

TRUE if the gradient can be edited.

Since: 2.4

gimp_gradient_get_uniform_samples ()

gboolean
+gimp_gradient_get_uniform_samples (const gchar *name,
+                                   gint num_samples,
+                                   gboolean reverse,
+                                   gint *num_color_samples,
+                                   gdouble **color_samples);

Sample the specified in uniform parts.

This procedure samples the active gradient in the specified number +of uniform parts. It returns a list of floating-point values which +correspond to the RGBA values for each sample. The minimum number of +samples to take is 2, in which case the returned colors will +correspond to the { 0.0, 1.0 } positions in the gradient. For +example, if the number of samples is 3, the procedure will return +the colors at positions { 0.0, 0.5, 1.0 }.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

name	The gradient name.
num_samples	The number of samples to take.
reverse	Use the reverse gradient.
num_color_samples	Length of the color_samples array (4 * num_samples).
color_samples	Color samples: { R1, G1, B1, A1, ..., Rn, Gn, Bn, An }.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_get_custom_samples ()

gboolean
+gimp_gradient_get_custom_samples (const gchar *name,
+                                  gint num_samples,
+                                  const gdouble *positions,
+                                  gboolean reverse,
+                                  gint *num_color_samples,
+                                  gdouble **color_samples);

Sample the specified gradient in custom positions.

This procedure samples the active gradient in the specified number +of points. The procedure will sample the gradient in the specified +positions from the list. The left endpoint of the gradient +corresponds to position 0.0, and the right endpoint corresponds to +1.0. The procedure returns a list of floating-point values which +correspond to the RGBA values for each sample.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

name	The gradient name.
num_samples	The number of samples to take.
positions	The list of positions to sample along the gradient.
reverse	Use the reverse gradient.
num_color_samples	Length of the color_samples array (4 * num_samples).
color_samples	Color samples: { R1, G1, B1, A1, ..., Rn, Gn, Bn, An }.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_get_number_of_segments ()

gint
+gimp_gradient_get_number_of_segments (const gchar *name);

Returns the number of segments of the specified gradient

This procedure returns the number of segments of the specified +gradient.

Parameters

+++++ + + + + + +

name

The gradient name.

Returns

Number of segments.

Since: 2.6

gimp_gradient_segment_get_left_color ()

gboolean
+gimp_gradient_segment_get_left_color (const gchar *name,
+                                      gint segment,
+                                      GimpRGB *color,
+                                      gdouble *opacity);

Retrieves the left endpoint color of the specified segment

This procedure retrieves the left endpoint color of the specified +segment of the specified gradient.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

name	The gradient name.
segment	The index of the segment within the gradient.
color	The return color.
opacity	The opacity of the endpoint.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_set_left_color ()

gboolean
+gimp_gradient_segment_set_left_color (const gchar *name,
+                                      gint segment,
+                                      const GimpRGB *color,
+                                      gdouble opacity);

Sets the left endpoint color of the specified segment

This procedure sets the left endpoint color of the specified segment +of the specified gradient.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

name	The gradient name.
segment	The index of the segment within the gradient.
color	The color to set.
opacity	The opacity to set for the endpoint.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_get_right_color ()

gboolean
+gimp_gradient_segment_get_right_color (const gchar *name,
+                                       gint segment,
+                                       GimpRGB *color,
+                                       gdouble *opacity);

Retrieves the right endpoint color of the specified segment

This procedure retrieves the right endpoint color of the specified +segment of the specified gradient.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

name	The gradient name.
segment	The index of the segment within the gradient.
color	The return color.
opacity	The opacity of the endpoint.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_set_right_color ()

gboolean
+gimp_gradient_segment_set_right_color (const gchar *name,
+                                       gint segment,
+                                       const GimpRGB *color,
+                                       gdouble opacity);

Sets the right endpoint color of the specified segment

This procedure sets the right endpoint color of the specified +segment of the specified gradient.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

name	The gradient name.
segment	The index of the segment within the gradient.
color	The color to set.
opacity	The opacity to set for the endpoint.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_get_left_pos ()

gboolean
+gimp_gradient_segment_get_left_pos (const gchar *name,
+                                    gint segment,
+                                    gdouble *pos);

Retrieves the left endpoint position of the specified segment

This procedure retrieves the left endpoint position of the specified +segment of the specified gradient.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

name	The gradient name.
segment	The index of the segment within the gradient.
pos	The return position.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_set_left_pos ()

gboolean
+gimp_gradient_segment_set_left_pos (const gchar *name,
+                                    gint segment,
+                                    gdouble pos,
+                                    gdouble *final_pos);

Sets the left endpoint position of the specified segment

This procedure sets the left endpoint position of the specified +segment of the specified gradient. The final position will be +between the position of the middle point to the left to the middle +point of the current segment. +This procedure returns the final position.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

name	The gradient name.
segment	The index of the segment within the gradient.
pos	The position to set the guidepoint to.
final_pos	The return position.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_get_middle_pos ()

gboolean
+gimp_gradient_segment_get_middle_pos (const gchar *name,
+                                      gint segment,
+                                      gdouble *pos);

Retrieves the middle point position of the specified segment

This procedure retrieves the middle point position of the specified +segment of the specified gradient.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

name	The gradient name.
segment	The index of the segment within the gradient.
pos	The return position.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_set_middle_pos ()

gboolean
+gimp_gradient_segment_set_middle_pos (const gchar *name,
+                                      gint segment,
+                                      gdouble pos,
+                                      gdouble *final_pos);

Sets the middle point position of the specified segment

This procedure sets the middle point position of the specified +segment of the specified gradient. The final position will be +between the two endpoints of the segment. +This procedure returns the final position.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

name	The gradient name.
segment	The index of the segment within the gradient.
pos	The position to set the guidepoint to.
final_pos	The return position.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_get_right_pos ()

gboolean
+gimp_gradient_segment_get_right_pos (const gchar *name,
+                                     gint segment,
+                                     gdouble *pos);

Retrieves the right endpoint position of the specified segment

This procedure retrieves the right endpoint position of the +specified segment of the specified gradient.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

name	The gradient name.
segment	The index of the segment within the gradient.
pos	The return position.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_set_right_pos ()

gboolean
+gimp_gradient_segment_set_right_pos (const gchar *name,
+                                     gint segment,
+                                     gdouble pos,
+                                     gdouble *final_pos);

Sets the right endpoint position of the specified segment

This procedure sets the right endpoint position of the specified +segment of the specified gradient. The final position will be +between the position of the middle point of the current segment and +the middle point of the segment to the right. +This procedure returns the final position.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

name	The gradient name.
segment	The index of the segment within the gradient.
pos	The position to set the guidepoint to.
final_pos	The return position.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_get_blending_function ()

gboolean
+gimp_gradient_segment_get_blending_function
+                               (const gchar *name,
+                                gint segment,
+                                GimpGradientSegmentType *blend_func);

Retrieves the gradient segment's blending function

This procedure retrieves the blending function of the segment at the +specified gradient name and segment index.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

name	The gradient name.
segment	The index of the segment within the gradient.
blend_func	The blending function of the segment.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_get_coloring_type ()

gboolean
+gimp_gradient_segment_get_coloring_type
+                               (const gchar *name,
+                                gint segment,
+                                GimpGradientSegmentColor *coloring_type);

Retrieves the gradient segment's coloring type

This procedure retrieves the coloring type of the segment at the +specified gradient name and segment index.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

name	The gradient name.
segment	The index of the segment within the gradient.
coloring_type	The coloring type of the segment.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_range_set_blending_function ()

gboolean
+gimp_gradient_segment_range_set_blending_function
+                               (const gchar *name,
+                                gint start_segment,
+                                gint end_segment,
+                                GimpGradientSegmentType blending_function);

Change the blending function of a segments range

This function changes the blending function of a segment range to +the specified blending function.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

name	The gradient name.
start_segment	The index of the first segment to operate on.
end_segment	The index of the last segment to operate on. If negative, the selection will extend to the end of the string.
blending_function	The blending function.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_range_set_coloring_type ()

gboolean
+gimp_gradient_segment_range_set_coloring_type
+                               (const gchar *name,
+                                gint start_segment,
+                                gint end_segment,
+                                GimpGradientSegmentColor coloring_type);

Change the coloring type of a segments range

This function changes the coloring type of a segment range to the +specified coloring type.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

name	The gradient name.
start_segment	The index of the first segment to operate on.
end_segment	The index of the last segment to operate on. If negative, the selection will extend to the end of the string.
coloring_type	The coloring type.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_range_flip ()

gboolean
+gimp_gradient_segment_range_flip (const gchar *name,
+                                  gint start_segment,
+                                  gint end_segment);

Flip the segment range

This function flips a segment range.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

name	The gradient name.
start_segment	The index of the first segment to operate on.
end_segment	The index of the last segment to operate on. If negative, the selection will extend to the end of the string.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_range_replicate ()

gboolean
+gimp_gradient_segment_range_replicate (const gchar *name,
+                                       gint start_segment,
+                                       gint end_segment,
+                                       gint replicate_times);

Replicate the segment range

This function replicates a segment range a given number of times. +Instead of the original segment range, several smaller scaled copies +of it will appear in equal widths.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

name	The gradient name.
start_segment	The index of the first segment to operate on.
end_segment	The index of the last segment to operate on. If negative, the selection will extend to the end of the string.
replicate_times	The number of times to replicate.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_range_split_midpoint ()

gboolean
+gimp_gradient_segment_range_split_midpoint
+                               (const gchar *name,
+                                gint start_segment,
+                                gint end_segment);

Splits each segment in the segment range at midpoint

This function splits each segment in the segment range at its +midpoint.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

name	The gradient name.
start_segment	The index of the first segment to operate on.
end_segment	The index of the last segment to operate on. If negative, the selection will extend to the end of the string.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_range_split_uniform ()

gboolean
+gimp_gradient_segment_range_split_uniform
+                               (const gchar *name,
+                                gint start_segment,
+                                gint end_segment,
+                                gint split_parts);

Splits each segment in the segment range uniformly

This function splits each segment in the segment range uniformly +according to the number of times specified by the parameter.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

name	The gradient name.
start_segment	The index of the first segment to operate on.
end_segment	The index of the last segment to operate on. If negative, the selection will extend to the end of the string.
split_parts	The number of uniform divisions to split each segment to.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_range_delete ()

gboolean
+gimp_gradient_segment_range_delete (const gchar *name,
+                                    gint start_segment,
+                                    gint end_segment);

Delete the segment range

This function deletes a segment range.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

name	The gradient name.
start_segment	The index of the first segment to operate on.
end_segment	The index of the last segment to operate on. If negative, the selection will extend to the end of the string.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_range_redistribute_handles ()

gboolean
+gimp_gradient_segment_range_redistribute_handles
+                               (const gchar *name,
+                                gint start_segment,
+                                gint end_segment);

Uniformly redistribute the segment range's handles

This function redistributes the handles of the specified segment +range of the specified gradient, so they'll be evenly spaced.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

name	The gradient name.
start_segment	The index of the first segment to operate on.
end_segment	The index of the last segment to operate on. If negative, the selection will extend to the end of the string.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_range_blend_colors ()

gboolean
+gimp_gradient_segment_range_blend_colors
+                               (const gchar *name,
+                                gint start_segment,
+                                gint end_segment);

Blend the colors of the segment range.

This function blends the colors (but not the opacity) of the +segments' range of the gradient. Using it, the colors' transition +will be uniform across the range.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

name	The gradient name.
start_segment	The index of the first segment to operate on.
end_segment	The index of the last segment to operate on. If negative, the selection will extend to the end of the string.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_range_blend_opacity ()

gboolean
+gimp_gradient_segment_range_blend_opacity
+                               (const gchar *name,
+                                gint start_segment,
+                                gint end_segment);

Blend the opacity of the segment range.

This function blends the opacity (but not the colors) of the +segments' range of the gradient. Using it, the opacity's transition +will be uniform across the range.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

name	The gradient name.
start_segment	The index of the first segment to operate on.
end_segment	The index of the last segment to operate on. If negative, the selection will extend to the end of the string.

Returns

TRUE on success.

Since: 2.2

gimp_gradient_segment_range_move ()

gdouble
+gimp_gradient_segment_range_move (const gchar *name,
+                                  gint start_segment,
+                                  gint end_segment,
+                                  gdouble delta,
+                                  gboolean control_compress);

Move the position of an entire segment range by a delta.

This function moves the position of an entire segment range by a +delta. The actual delta (which is returned) will be limited by the +control points of the neighboring segments.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

name	The gradient name.
start_segment	The index of the first segment to operate on.
end_segment	The index of the last segment to operate on. If negative, the selection will extend to the end of the string.
delta	The delta to move the segment range.
control_compress	Whether or not to compress the neighboring segments.

Returns

The final delta by which the range moved.

Since: 2.2