[cairo] [API] Export region data type

[Soeren Sandmann]

Hi,

I'd like to propose exporting the region data type for 1.10. There is
an implementation available in the public-region branch of this
repository:

        http://cgit.freedesktop.org/~sandmann/cairo-damage/log/?h=3Dpublic-=
region

        git://freedesktop.org/~sandmann/cairo-damage

My personal motivation is that I need them for the damage tracking
API, but regions are useful for necessary for any serious user of
cairo, so to avoid duplication of code, cairo should provide them.

Contents of the patch:

    - cairo_region_t becomes a malloced object

    - regions operators become two-operand rather than three-operand

    - API uses rectangles exclusively instead of boxes

    - cairo_rectangle_int_t is always defined with 'int' fields, no
      matter the size of the fix point data type.

    - cairo_region_create_boxes() is gone since it was only used
      in one place, which could be simplified considerably by
      calling cairo_region_union_rect() repeatedly instead.

    - Two new entry points: cairo_region_union() and
      cairo_region_contains_point().

    - cairo_region_clear() is gone since it wasn't used and isn't all
      that useful.

The internals of cairo are much nicer with malloced regions; for
example, all the "has_region" fields are gone, since regions can now
be NULL. Somewhat surprisingly, all this results in a net reduction of
12 lines of code:

    dhcp-100-3-82:~/vertigo/cairo% git diff master | diffstat
    ...
     18 files changed, 508 insertions(+), 520 deletions(-)

Here is the new API; comments appreciated:

    typedef struct _cairo_region cairo_region_t;

    typedef struct _cairo_rectangle_int {
        int x, y;
        unsigned int width, height;
    } cairo_rectangle_int_t;

    typedef enum _cairo_region_overlap {
        CAIRO_REGION_OVERLAP_IN,           /* completely inside region */
        CAIRO_REGION_OVERLAP_OUT,          /* completely outside region */
        CAIRO_REGION_OVERLAP_PART,         /* partly inside region */
    } cairo_region_overlap_t;

    cairo_public cairo_region_t *
    cairo_region_create (void);

    cairo_public cairo_region_t *
    cairo_region_create_rectangle (cairo_rectangle_int_t *rect);

    cairo_public cairo_region_t *
    cairo_region_copy (cairo_region_t *original);

    cairo_public void
    cairo_region_destroy (cairo_region_t *region);

    cairo_public cairo_status_t
    cairo_region_status (cairo_region_t *region);

    cairo_public void
    cairo_region_get_extents (cairo_region_t        *region,
                              cairo_rectangle_int_t *extents);

    cairo_public int
    cairo_region_num_rectangles (cairo_region_t *region);

    cairo_public void
    cairo_region_get_rectangle (cairo_region_t        *region,
                                int                    nth_rectangle,
                                cairo_rectangle_int_t *rectangle);

    cairo_public cairo_bool_t
    cairo_region_empty (cairo_region_t *region);

    cairo_public cairo_region_overlap_t
    cairo_region_contains_rectangle (cairo_region_t *region,
                                    const cairo_rectangle_int_t *rect);

    cairo_public cairo_bool_t
    cairo_region_contains_point (cairo_region_t *region, int x, int y);

    cairo_public void
    cairo_region_translate (cairo_region_t *region, int dx, int dy);

    cairo_public cairo_status_t
    cairo_region_subtract (cairo_region_t *dst, cairo_region_t *other);

    cairo_public cairo_status_t
    cairo_region_intersect (cairo_region_t *dst, cairo_region_t *other);

    cairo_public cairo_status_t
    cairo_region_union (cairo_region_t *dst, cairo_region_t *other);

    cairo_public cairo_status_t
    cairo_region_union_rectangle (cairo_region_t *dst,
                                  cairo_rectangle_int_t *rect);

One thing that may be interesting, is using (x, y, width, height)
parameters instead of rectangles. That way the cairo_rectangle_int_t
data type doesn't have to be exported.


Thanks,
Søren