canvas clipping path

[Mathieu Lacage <mathieu gnu org>]

hi all,

After some long and painful looking at the canvas code, I have to ask
here what the hell the clip_path parameter of the update class method of
the CanvasItem is used for.

Looking at the gnome-canvas.c code, I see that updates are triggered by
either a direct call to gnome_canvas_update_now (eveeeeel) or a trigger
of a the idle handler of the canvas by the glib main loop.

In both cases, the code ends in do_update which does this:
       if (canvas->need_update) {
                double affine[6];

                art_affine_identity (affine);
                gnome_canvas_item_invoke_update (canvas->root, affine,
NULL, 0);
                canvas->need_update = FALSE;
        }

        /* Pick new current item */

        while (canvas->need_repick) {
                canvas->need_repick = FALSE;
                pick_current_item (canvas, &canvas->pick_event);
        }

        /* Paint if able to */

        if (GTK_WIDGET_DRAWABLE (canvas))
                paint (canvas);


the butt of this function is the call to gnome_canvas_item_invoke_update
(canvas->root, affine, NULL, 0); folowed by the call to paint (canvas);

paint (canvas) will trigger the draw or the render class methods which
is not of much interest to us.
On the other hand, gnome_canvas_item_invoke_update will trigger a chain
of update calls from the root item to the most bottom items in the
intanciation hierarhy: the root item beeing a CanvasGroup, it will do
this:
        for (list = group->item_list; list; list = list->next) {
                i = list->data;

                gnome_canvas_item_invoke_update (i, affine, clip_path,
flags);

                child_bbox.x0 = i->x1;
                child_bbox.y0 = i->y1;
                child_bbox.x1 = i->x2;
                child_bbox.y1 = i->y2;
                art_drect_union (&bbox, &bbox, &child_bbox);
        }

which is nothing but a simple looping over its children to make sure
they have all been updated.

So, it seems that everywhere an update method is called, it will keep
around the clip_path parameter passed to the root item which is always
NULL and which cannot be changed in any way. Am I right in this
assumption ?

If I am right, I can guess the historical reasons for this. If i am
wrong, I have two questions:
1) what kind of code path can lead to a non-NULL clip_path parameter ?
2) as an application developer not writing CanvasItems, could I have
interest in playing with the clip_path. If so, how should I access it ?
I am really confused as to what it is supposed to represent: it could
have represented the area to be redrawn but this is not the case. 

any help and enlightenments are appreciated.

Mathieu

-- 
Mathieu Lacage <mathieu gnu org>
Portable: <lacage orange fr>