Cairo masking - is there something I'm missing?

Question

So I'm trying to set up a mask in Cairo, but can't get it to make any difference. Below I have a simple program based off the one here: http://snipplr.com/view/22584/cairo-hello-world-examble/.

I'm setting a completely transparent mask so nothing should be getting drawn, but it doesn't seem to have any effect - the text still gets drawn. My code is below. What am I missing?

Thanks!

int main(int argc, char* argv[])
{                               
    cairo_surface_t* surface;     
    cairo_t* cr;                  

    surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32, 200, 40);
    cr = cairo_create (surface);

    //****
    // Here I create a pattern with an alpha of zero and set it to be cairo's mask
    // According to http://www.cairographics.org/manual/cairo-context.html#cairo-mask
    // "Opaque areas of pattern are painted with the source, transparent areas are not painted."
    // Shouldn't this make it so nothing gets drawn?
    //****

    cairo_pattern_t* nothing = cairo_pattern_create_rgba(0,0,0,0);
    cairo_mask (cr, nothing);

    cairo_text_extents_t te;
    cairo_set_source_rgb (cr, 0.0, 0.0, 0.0);
    cairo_select_font_face (cr, "Georgia",
                          CAIRO_FONT_SLANT_NORMAL, CAIRO_FONT_WEIGHT_BOLD);
    cairo_set_font_size (cr, 20.0);
    cairo_text_extents (cr, "hello cairo!", &te);
    cairo_move_to (cr, 20, 20);
    cairo_show_text (cr, "hello cairo!");
    cairo_fill(cr);

    // An image gets drawn that says "hello cairo!" in big letters
    cairo_surface_write_to_png(surface, "hello_cairo.png");

    return 0;
}

Answer 1

Ok I figured it out. I was expecting cairo_mask() to behave like cairo_clip(). (in cairo_clip() it establishes a clip path that clips every element drawn afterward)

cairo_mask is explained very simply: "cairo_mask -- Paint current source fill pattern using alpha channel mask pattern." That's exactly what it does - fills in the whole screen with the current fill pattern and blends it by whatever alpha is for that pixel on the mask.