surface clipping

[Steven J Abner]

On Wed, Jul 31 2024 at 11:22:55 PM +0000, Steven J Abner 
<pheonix.sja at att.net> wrote:
> This is due to my learning

In hopes the someone may find this helpful, for doing surfaces. The 
aforementioned clipping works on internal surfaces, but one may come 
across external needs. If you should notice display flashes of white 
and/or bleed through of the surface from the below surface, here is the 
solution:
static void
_create_interface_clip(PhxInterface *iface, cairo_t *cr) {

  PhxRectangle *dbox = &iface->draw_box;
  cairo_new_path(cr);
    /* counter-clockwise path */
  cairo_move_to(cr, dbox->w, 0);
  cairo_line_to(cr, 0, 0);
  cairo_line_to(cr, 0, dbox->h);
  cairo_line_to(cr, dbox->w, dbox->h);
  cairo_close_path(cr);

  uint16_t ndx = 0;
  do {
    PhxNexus *nexus = iface->nexus[ndx];
      /* clockwise sub-path */
    cairo_rectangle(cr, nexus->mete_box.x, nexus->mete_box.y,
                        nexus->mete_box.w, nexus->mete_box.h);
  } while ((++ndx) < iface->ncount);
  cairo_clip(cr);
}

This is semi from cairo cookbook example on clipping. The concept is to 
'knockout' all surfaces above the background. This does stop both 
flickering and momentary bleed-thru. I should also add that it's not 
normally needed, it is fringe case of creating windowless windows as 
surfaces.
Steve