Commit 3e96cfe8 authored by Benjamin Otte's avatar Benjamin Otte
Browse files

Deprecate the GdkRegion API

Includes fixing all callers to use the cairo region API instead. This is
usually just replacing the function names, the only difference is
gdk_region_get_rectangles() being replaced by
cairo_region_num_rectangles() and cairo_region_get_rectangle() which
required a bit more work.

https://bugzilla.gnome.org/show_bug.cgi?id=613284
parent 52200eee
......@@ -47,15 +47,12 @@ Defines the x and y coordinates of a point.
@x: the x coordinate of the point.
@y: the y coordinate of the point.
<!-- ##### STRUCT GdkRectangle ##### -->
<!-- ##### TYPEDEF GdkRectangle ##### -->
<para>
Defines the position and size of a rectangle.
Defines the position and size of a rectangle. It is identical to
#cairo_rectangle_int_t.
</para>
@x: the x coordinate of the left edge of the rectangle.
@y: the y coordinate of the top of the rectangle.
@width: the width of the rectangle.
@height: the height of the rectangle.
<!-- ##### FUNCTION gdk_rectangle_intersect ##### -->
<para>
......
......@@ -258,7 +258,7 @@ gdk_directfb_clip_region (GdkDrawable *drawable,
GDKDFB_RECTANGLE_VALS_FROM_BOX( &private->paint_region.extents ),
private->paint_region.numRects );
gdk_region_intersect (ret_clip, &private->paint_region);
cairo_region_intersect (ret_clip, &private->paint_region);
}
if (gc)
......@@ -273,13 +273,13 @@ gdk_directfb_clip_region (GdkDrawable *drawable,
if (gc->clip_x_origin || gc->clip_y_origin)
{
gdk_region_offset (ret_clip, -gc->clip_x_origin, -gc->clip_y_origin);
gdk_region_intersect (ret_clip, region);
gdk_region_offset (ret_clip, gc->clip_x_origin, gc->clip_y_origin);
cairo_region_translate (ret_clip, -gc->clip_x_origin, -gc->clip_y_origin);
cairo_region_intersect (ret_clip, region);
cairo_region_translate (ret_clip, gc->clip_x_origin, gc->clip_y_origin);
}
else
{
gdk_region_intersect (ret_clip, region);
cairo_region_intersect (ret_clip, region);
}
}
......@@ -327,7 +327,7 @@ gdk_directfb_clip_region (GdkDrawable *drawable,
D_DEBUG_AT( GDKDFB_DrawClip, " -> clipping child [ %4d,%4d - %4dx%4d ] (%ld boxes)\n",
GDKDFB_RECTANGLE_VALS_FROM_BOX( &temp.extents ), temp.numRects );
gdk_region_subtract (ret_clip, &temp);
cairo_region_subtract (ret_clip, &temp);
}
}
......@@ -739,7 +739,7 @@ gdk_directfb_draw_points (GdkDrawable *drawable,
while (npoints > 0)
{
if (gdk_region_point_in (&clip, points->x, points->y))
if (cairo_region_contains_point (&clip, points->x, points->y))
{
impl->surface->FillRectangle (impl->surface,
points->x, points->y, 1, 1);
......@@ -940,7 +940,7 @@ gdk_directfb_draw_image (GdkDrawable *drawable,
gdk_directfb_clip_region (drawable, gc, &dest_rect, &clip);
if (!gdk_region_empty (&clip))
if (!cairo_region_is_empty (&clip))
{
DFBRectangle src_rect = { xsrc, ysrc, width, height };
......@@ -1218,15 +1218,15 @@ gdk_directfb_draw_pixbuf (GdkDrawable *drawable,
tmp_rect.width = width;
tmp_rect.height = height;
drect = gdk_region_rectangle (&tmp_rect);
drect = cairo_region_create_rectangle (&tmp_rect);
clip = gdk_drawable_get_clip_region (drawable);
gdk_region_intersect (drect, clip);
cairo_region_intersect (drect, clip);
gdk_region_get_clipbox (drect, &tmp_rect);
cairo_region_get_extents (drect, &tmp_rect);
gdk_region_destroy (drect);
gdk_region_destroy (clip);
cairo_region_destroy (drect);
cairo_region_destroy (clip);
if (tmp_rect.width == 0 ||
tmp_rect.height == 0)
......
......@@ -91,24 +91,24 @@ _gdk_directfb_window_scroll (GdkWindow *window,
/* Move the current invalid region */
if (private->update_area)
gdk_region_offset (private->update_area, dx, dy);
cairo_region_translate (private->update_area, dx, dy);
if (GDK_WINDOW_IS_MAPPED (window))
{
GdkRectangle clip_rect = { 0, 0, impl->width, impl->height };
GdkRectangle rect = { dx, dy, impl->width, impl->height };
invalidate_region = gdk_region_rectangle (&clip_rect);
invalidate_region = cairo_region_create_rectangle (&clip_rect);
if (gdk_rectangle_intersect (&rect, &clip_rect, &rect) &&
(!private->update_area ||
!gdk_region_rect_in (private->update_area, &rect)))
!cairo_region_contains_rectangle (private->update_area, &rect)))
{
GdkRegion *region;
region = gdk_region_rectangle (&rect);
gdk_region_subtract (invalidate_region, region);
gdk_region_destroy (region);
region = cairo_region_create_rectangle (&rect);
cairo_region_subtract (invalidate_region, region);
cairo_region_destroy (region);
if (impl->surface)
{
......@@ -141,7 +141,7 @@ _gdk_directfb_window_scroll (GdkWindow *window,
if (invalidate_region)
{
gdk_window_invalidate_region (window, invalidate_region, TRUE);
gdk_region_destroy (invalidate_region);
cairo_region_destroy (invalidate_region);
}
}
......@@ -188,31 +188,31 @@ _gdk_directfb_window_move_region (GdkWindow *window,
return;
GdkRectangle clip_rect = { 0, 0, impl->width, impl->height };
window_clip = gdk_region_rectangle (&clip_rect);
window_clip = cairo_region_create_rectangle (&clip_rect);
/* compute source regions */
src_region = gdk_region_copy (region);
brought_in = gdk_region_copy (region);
gdk_region_intersect (src_region, window_clip);
src_region = cairo_region_copy (region);
brought_in = cairo_region_copy (region);
cairo_region_intersect (src_region, window_clip);
gdk_region_subtract (brought_in, src_region);
gdk_region_offset (brought_in, dx, dy);
cairo_region_subtract (brought_in, src_region);
cairo_region_translate (brought_in, dx, dy);
/* compute destination regions */
dest_region = gdk_region_copy (src_region);
gdk_region_offset (dest_region, dx, dy);
gdk_region_intersect (dest_region, window_clip);
gdk_region_get_clipbox (dest_region, &dest_extents);
dest_region = cairo_region_copy (src_region);
cairo_region_translate (dest_region, dx, dy);
cairo_region_intersect (dest_region, window_clip);
cairo_region_get_extents (dest_region, &dest_extents);
gdk_region_destroy (window_clip);
cairo_region_destroy (window_clip);
/* calculating moving part of current invalid area */
moving_invalid_region = NULL;
if (private->update_area)
{
moving_invalid_region = gdk_region_copy (private->update_area);
gdk_region_intersect (moving_invalid_region, src_region);
gdk_region_offset (moving_invalid_region, dx, dy);
moving_invalid_region = cairo_region_copy (private->update_area);
cairo_region_intersect (moving_invalid_region, src_region);
cairo_region_translate (moving_invalid_region, dx, dy);
}
/* invalidate all of the src region */
......@@ -220,18 +220,18 @@ _gdk_directfb_window_move_region (GdkWindow *window,
/* un-invalidate destination region */
if (private->update_area)
gdk_region_subtract (private->update_area, dest_region);
cairo_region_subtract (private->update_area, dest_region);
/* invalidate moving parts of existing update area */
if (moving_invalid_region)
{
gdk_window_invalidate_region (window, moving_invalid_region, FALSE);
gdk_region_destroy (moving_invalid_region);
cairo_region_destroy (moving_invalid_region);
}
/* invalidate area brought in from off-screen */
gdk_window_invalidate_region (window, brought_in, FALSE);
gdk_region_destroy (brought_in);
cairo_region_destroy (brought_in);
/* Actually do the moving */
if (impl->surface)
......@@ -250,8 +250,8 @@ _gdk_directfb_window_move_region (GdkWindow *window,
impl->surface->SetClip (impl->surface, NULL);
impl->surface->Flip(impl->surface,&destination,0);
}
gdk_region_destroy (src_region);
gdk_region_destroy (dest_region);
cairo_region_destroy (src_region);
cairo_region_destroy (dest_region);
}
#define __GDK_GEOMETRY_X11_C__
......
......@@ -227,7 +227,7 @@ gdk_window_impl_directfb_get_visible_region (GdkDrawable *drawable)
D_DEBUG_AT( GDKDFB_Window, " -> returning %4d,%4d-%4dx%4d\n", drect.x, drect.y, drect.w, drect.h );
return gdk_region_rectangle (&rect);
return cairo_region_create_rectangle (&rect);
}
static void
......@@ -2648,7 +2648,7 @@ gdk_window_impl_directfb_begin_paint_region (GdkPaintable *paintable,
DFB_RECTANGLE_VALS_FROM_REGION( &impl->paint_region.extents ), impl->paint_region.numRects );
/* Add the new region to the paint region... */
gdk_region_union (&impl->paint_region, region);
cairo_region_union (&impl->paint_region, region);
}
else
{
......@@ -2668,7 +2668,7 @@ gdk_window_impl_directfb_begin_paint_region (GdkPaintable *paintable,
DFB_RECTANGLE_VALS_FROM_REGION( &impl->paint_region.extents ), impl->paint_region.numRects );
/* ...but clip the initial/compound result against the clip region. */
gdk_region_intersect (&impl->paint_region, &impl->clip_region);
cairo_region_intersect (&impl->paint_region, &impl->clip_region);
D_DEBUG_AT( GDKDFB_Window, " -> clipped %4d,%4d-%4dx%4d (%ld boxes)\n",
DFB_RECTANGLE_VALS_FROM_REGION( &impl->paint_region.extents ), impl->paint_region.numRects );
......
......@@ -977,6 +977,7 @@ gdk_pixmap_lookup_for_display
#if IN_HEADER(__GDK_REGION_H__)
#if IN_FILE(__GDK_REGION_GENERIC_C__)
#ifndef GDK_DISABLE_DEPRECATED
gdk_region_copy
gdk_region_destroy
gdk_region_empty
......@@ -998,12 +999,15 @@ gdk_region_union_with_rect
gdk_region_xor
#endif
#endif
#endif
#if IN_HEADER(__GDK_REGION_H__)
#if IN_FILE(__GDK_POLYREG_GENERIC_C__)
#ifndef GDK_DISABLE_DEPRECATED
gdk_region_polygon
#endif
#endif
#endif
#if IN_HEADER(__GDK_RGB_H__)
#if IN_FILE(__GDK_RGB_C__)
......
......@@ -1059,7 +1059,7 @@ gdk_drawable_real_get_composite_drawable (GdkDrawable *drawable,
* but no area outside of this region will be affected by drawing
* primitives.
*
* Returns: a #GdkRegion. This must be freed with gdk_region_destroy()
* Returns: a #GdkRegion. This must be freed with cairo_region_destroy()
* when you are done.
**/
GdkRegion *
......@@ -1079,7 +1079,7 @@ gdk_drawable_get_clip_region (GdkDrawable *drawable)
* obscured by other windows, but no area outside of this region
* is visible.
*
* Returns: a #GdkRegion. This must be freed with gdk_region_destroy()
* Returns: a #GdkRegion. This must be freed with cairo_region_destroy()
* when you are done.
**/
GdkRegion *
......@@ -1100,7 +1100,7 @@ gdk_drawable_real_get_visible_region (GdkDrawable *drawable)
gdk_drawable_get_size (drawable, &rect.width, &rect.height);
return gdk_region_rectangle (&rect);
return cairo_region_create_rectangle (&rect);
}
/**
......@@ -1431,15 +1431,15 @@ gdk_drawable_real_draw_pixbuf (GdkDrawable *drawable,
tmp_rect.width = width;
tmp_rect.height = height;
drect = gdk_region_rectangle (&tmp_rect);
drect = cairo_region_create_rectangle (&tmp_rect);
clip = gdk_drawable_get_clip_region (drawable);
gdk_region_intersect (drect, clip);
cairo_region_intersect (drect, clip);
gdk_region_get_clipbox (drect, &tmp_rect);
cairo_region_get_extents (drect, &tmp_rect);
gdk_region_destroy (drect);
gdk_region_destroy (clip);
cairo_region_destroy (drect);
cairo_region_destroy (clip);
if (tmp_rect.width == 0 ||
tmp_rect.height == 0)
......
......@@ -473,7 +473,7 @@ gdk_event_copy (const GdkEvent *event)
case GDK_EXPOSE:
case GDK_DAMAGE:
if (event->expose.region)
new_event->expose.region = gdk_region_copy (event->expose.region);
new_event->expose.region = cairo_region_copy (event->expose.region);
break;
case GDK_SETTING:
......@@ -551,7 +551,7 @@ gdk_event_free (GdkEvent *event)
case GDK_EXPOSE:
case GDK_DAMAGE:
if (event->expose.region)
gdk_region_destroy (event->expose.region);
cairo_region_destroy (event->expose.region);
break;
case GDK_MOTION_NOTIFY:
......
......@@ -205,9 +205,9 @@ gdk_gc_finalize (GObject *object)
GdkGCPrivate *priv = GDK_GC_GET_PRIVATE (gc);
if (priv->clip_region)
gdk_region_destroy (priv->clip_region);
cairo_region_destroy (priv->clip_region);
if (priv->old_clip_region)
gdk_region_destroy (priv->old_clip_region);
cairo_region_destroy (priv->old_clip_region);
if (priv->clip_mask)
g_object_unref (priv->clip_mask);
if (priv->old_clip_mask)
......@@ -293,7 +293,7 @@ gdk_gc_set_values (GdkGC *gc,
if (priv->clip_region)
{
gdk_region_destroy (priv->clip_region);
cairo_region_destroy (priv->clip_region);
priv->clip_region = NULL;
}
}
......@@ -550,7 +550,7 @@ _gdk_gc_set_clip_region_real (GdkGC *gc,
}
if (priv->clip_region)
gdk_region_destroy (priv->clip_region);
cairo_region_destroy (priv->clip_region);
priv->clip_region = region;
......@@ -585,9 +585,9 @@ _gdk_gc_add_drawable_clip (GdkGC *gc,
if (priv->region_tag_applied)
_gdk_gc_remove_drawable_clip (gc);
region = gdk_region_copy (region);
region = cairo_region_copy (region);
if (offset_x != 0 || offset_y != 0)
gdk_region_offset (region, offset_x, offset_y);
cairo_region_translate (region, offset_x, offset_y);
if (priv->clip_mask)
{
......@@ -596,7 +596,7 @@ _gdk_gc_add_drawable_clip (GdkGC *gc,
GdkGC *tmp_gc;
GdkColor black = {0, 0, 0, 0};
GdkRectangle r;
GdkOverlapType overlap;
cairo_region_overlap_t overlap;
gdk_drawable_get_size (priv->clip_mask, &w, &h);
......@@ -609,8 +609,8 @@ _gdk_gc_add_drawable_clip (GdkGC *gc,
* the region, so we try to avoid allocating bitmaps that are just fully
* set or completely unset.
*/
overlap = gdk_region_rect_in (region, &r);
if (overlap == GDK_OVERLAP_RECTANGLE_PART)
overlap = cairo_region_contains_rectangle (region, &r);
if (overlap == CAIRO_REGION_OVERLAP_PART)
{
/* The region and the mask intersect, create a new clip mask that
includes both areas */
......@@ -631,12 +631,12 @@ _gdk_gc_add_drawable_clip (GdkGC *gc,
gdk_gc_set_clip_mask (gc, new_mask);
g_object_unref (new_mask);
}
else if (overlap == GDK_OVERLAP_RECTANGLE_OUT)
else if (overlap == CAIRO_REGION_OVERLAP_OUT)
{
/* No intersection, set empty clip region */
GdkRegion *empty = gdk_region_new ();
GdkRegion *empty = cairo_region_create ();
gdk_region_destroy (region);
cairo_region_destroy (region);
priv->old_clip_mask = g_object_ref (priv->clip_mask);
priv->clip_region = empty;
_gdk_windowing_gc_set_clip_region (gc, empty, FALSE);
......@@ -644,7 +644,7 @@ _gdk_gc_add_drawable_clip (GdkGC *gc,
else
{
/* Completely inside region, don't set unnecessary clip */
gdk_region_destroy (region);
cairo_region_destroy (region);
return;
}
}
......@@ -653,7 +653,7 @@ _gdk_gc_add_drawable_clip (GdkGC *gc,
priv->old_clip_region = priv->clip_region;
priv->clip_region = region;
if (priv->old_clip_region)
gdk_region_intersect (region, priv->old_clip_region);
cairo_region_intersect (region, priv->old_clip_region);
_gdk_windowing_gc_set_clip_region (gc, priv->clip_region, FALSE);
}
......@@ -711,7 +711,7 @@ gdk_gc_set_clip_rectangle (GdkGC *gc,
_gdk_gc_remove_drawable_clip (gc);
if (rectangle)
region = gdk_region_rectangle (rectangle);
region = cairo_region_create_rectangle (rectangle);
else
region = NULL;
......@@ -738,7 +738,7 @@ gdk_gc_set_clip_region (GdkGC *gc,
_gdk_gc_remove_drawable_clip (gc);
if (region)
copy = gdk_region_copy (region);
copy = cairo_region_copy (region);
else
copy = NULL;
......@@ -1063,20 +1063,20 @@ gdk_gc_copy (GdkGC *dst_gc,
dst_gc->colormap = src_gc->colormap;
if (dst_priv->clip_region)
gdk_region_destroy (dst_priv->clip_region);
cairo_region_destroy (dst_priv->clip_region);
if (src_priv->clip_region)
dst_priv->clip_region = gdk_region_copy (src_priv->clip_region);
dst_priv->clip_region = cairo_region_copy (src_priv->clip_region);
else
dst_priv->clip_region = NULL;
dst_priv->region_tag_applied = src_priv->region_tag_applied;
if (dst_priv->old_clip_region)
gdk_region_destroy (dst_priv->old_clip_region);
cairo_region_destroy (dst_priv->old_clip_region);
if (src_priv->old_clip_region)
dst_priv->old_clip_region = gdk_region_copy (src_priv->old_clip_region);
dst_priv->old_clip_region = cairo_region_copy (src_priv->old_clip_region);
else
dst_priv->old_clip_region = NULL;
......
......@@ -288,9 +288,9 @@ add_damage (GdkOffscreenWindow *offscreen,
rect.height += 7;
}
damage = gdk_region_rectangle (&rect);
damage = cairo_region_create_rectangle (&rect);
_gdk_window_add_damage (offscreen->wrapper, damage);
gdk_region_destroy (damage);
cairo_region_destroy (damage);
}
static GdkDrawable *
......
......@@ -1255,7 +1255,7 @@ layout_iter_get_line_clip_region (PangoLayoutIter *iter,
line = pango_layout_iter_get_line_readonly (iter);
clip_region = gdk_region_new ();
clip_region = cairo_region_create ();
pango_layout_iter_get_line_extents (iter, NULL, &logical_rect);
baseline = pango_layout_iter_get_baseline (iter);
......@@ -1289,7 +1289,7 @@ layout_iter_get_line_clip_region (PangoLayoutIter *iter,
rect.width = PANGO_PIXELS (pixel_ranges[2*j + 1] - logical_rect.x) - x_off;
rect.height = PANGO_PIXELS (baseline - logical_rect.y + logical_rect.height) - y_off;
gdk_region_union_with_rect (clip_region, &rect);
cairo_region_union_rectangle (clip_region, &rect);
}
g_free (pixel_ranges);
......@@ -1380,7 +1380,7 @@ gdk_pango_layout_get_clip_region (PangoLayout *layout,
g_return_val_if_fail (PANGO_IS_LAYOUT (layout), NULL);
g_return_val_if_fail (index_ranges != NULL, NULL);
clip_region = gdk_region_new ();
clip_region = cairo_region_create ();
iter = pango_layout_get_iter (layout);
......@@ -1399,8 +1399,8 @@ gdk_pango_layout_get_clip_region (PangoLayout *layout,
index_ranges,
n_ranges);
gdk_region_union (clip_region, line_region);
gdk_region_destroy (line_region);
cairo_region_union (clip_region, line_region);
cairo_region_destroy (line_region);
}
while (pango_layout_iter_next_line (iter));
......
......@@ -481,7 +481,7 @@ gdk_region_polygon (const GdkPoint *points,
extents.y = MIN(points[0].y, points[2].y);
extents.width = MAX(points[0].x, points[2].x) - extents.x;
extents.height = MAX(points[0].y, points[2].y) - extents.y;
return gdk_region_rectangle (&extents);
return cairo_region_create_rectangle (&extents);
}
pETEs = g_new (EdgeTableEntry, n_points);
......
......@@ -10,6 +10,8 @@
* Creates a new empty #GdkRegion.
*
* Returns: a new empty #GdkRegion
*
* Deprecated: 2.22: Use cairo_region_create() instead.
*/
GdkRegion *
gdk_region_new (void)
......@@ -24,6 +26,8 @@ gdk_region_new (void)
* Creates a new region containing the area @rectangle.
*
* Return value: a new region
*
* Deprecated: 2.22: Use cairo_region_create_rectangle()
**/
GdkRegion *
gdk_region_rectangle (const GdkRectangle *rectangle)
......@@ -43,6 +47,8 @@ gdk_region_rectangle (const GdkRectangle *rectangle)
* Copies @region, creating an identical new region.
*
* Return value: a new region identical to @region
*
* Deprecated: 2.22: Use cairo_region_copy()
**/
GdkRegion *
gdk_region_copy (const GdkRegion *region)
......@@ -57,6 +63,7 @@ gdk_region_copy (const GdkRegion *region)
*
* Obtains the smallest rectangle which includes the entire #GdkRegion.
*
* Deprecated: 2.22: Use cairo_region_get_extents()
*/
void
gdk_region_get_clipbox (const GdkRegion *region,
......@@ -77,6 +84,8 @@ gdk_region_get_clipbox (const GdkRegion *region,
*
* Obtains the area covered by the region as a list of rectangles.
* The array returned in @rectangles must be freed with g_free().
*
* Deprecated: 2.22: Use cairo_region_num_rectangles() and cairo_region_get_rectangle() instead.
**/
void
gdk_region_get_rectangles (const GdkRegion *region,
......@@ -110,6 +119,8 @@ gdk_region_get_rectangles (const GdkRegion *region,
* Sets the area of @region to the union of the areas of @region and
* @rect. The resulting area is the set of pixels contained in
* either @region or @rect.
*
* Deprecated: 2.22: Use cairo_region_union_rectangle() instead.
**/
void
gdk_region_union_with_rect (GdkRegion *region,
......@@ -129,6 +140,8 @@ gdk_region_union_with_rect (GdkRegion *region,
* @region: a #GdkRegion
*
* Destroys a #GdkRegion.
*
* Deprecated: 2.22: Use cairo_region_destroy() instead.
*/
void
gdk_region_destroy (GdkRegion *region)
......@@ -146,6 +159,8 @@ gdk_region_destroy (GdkRegion *region)
* @dy: the distance to move the region vertically
*
* Moves a region the specified distance.
*
* Deprecated: 2.22: Use cairo_region_translate() instead.
*/
void
gdk_region_offset (GdkRegion *region,
......@@ -163,6 +178,8 @@ gdk_region_offset (GdkRegion *region,
*
* Resizes a region by the specified amount.
* Positive values shrink the region. Negative values expand it.
*
* Deprecated: 2.22: There is no replacement for this function.
*/
void
gdk_region_shrink (GdkRegion *region,
......@@ -198,6 +215,8 @@ gdk_region_shrink (GdkRegion *region,
* Sets the area of @source1 to the intersection of the areas of @source1
* and @source2. The resulting area is the set of pixels contained in
* both @source1 and @source2.
*
* Deprecated: 2.22: Use cairo_region_intersect() instead.
**/
void
gdk_region_intersect (GdkRegion *source1,
......@@ -217,6 +236,8 @@ gdk_region_intersect (GdkRegion *source1,
* Sets the area of @source1 to the union of the areas of @source1 and
* @source2. The resulting area is the set of pixels contained in
* either @source1 or @source2.
*
* Deprecated: 2.22: Use cairo_region_union() instead.
**/
void
gdk_region_union (GdkRegion *source1,
......@@ -235,6 +256,8 @@ gdk_region_union (GdkRegion *source1,
*
* Subtracts the area of @source2 from the area @source1. The resulting
* area is the set of pixels contained in @source1 but not in @source2.
*
* Deprecated: 2.22: Use cairo_region_subtract() instead.
**/