Clarify that fallback_resolution acts on a per-page granularity.

This explains why the SVG result from the fallback-resolution test
doesn't actually show multiple resolutions in effect at the same time.

src/cairo-surface.c

@@ -728,6 +728,11 @@ cairo_surface_get_device_offset (cairo_surface_t *surface,
  * still possible, but they are always performed at the native
  * device resolution. So this function has no effect on those
  * backends.
+ *
+ * NOTE: The fallback resolution only takes effect at the time of
+ * completing a page (with cairo_show_page() or cairo_copy_page()) so
+ * there is currently no way to have more than one fallback resolution
+ * in effect on a single page.
  **/
 void
 cairo_surface_set_fallback_resolution (cairo_surface_t	*surface,

test/fallback-resolution.c

@@ -125,6 +125,8 @@ main (void)
 
 	    draw (cr, SIZE, SIZE, ppi[page]);
 
+	    cairo_show_page (cr);
+
 	    /* Backend-specific means of "advancing a page" */
 	    switch (backend) {
 	    case PDF:
@@ -132,9 +134,23 @@ main (void)
 		cairo_show_page (cr);
 		break;
 	    case SVG:
+		/* Since the SVG backend doesn't natively support multiple
+		 * pages, we just move further down for each logical
+		 * page, then finally do a show_page at the end. */
 		if (page < num_pages - 1) {
 		    cairo_translate (cr, 0, SIZE);
 		} else {
+		    /* XXX: The goal of this test is to show the
+		     * effect of several different fallback
+		     * resolutions in a single output document. But
+		     * since fallback_resolution only takes effect at
+		     * the time of show_page, we only get once for the
+		     * SVG backend. I'm just re-setting the first one
+		     * here so we actually get legible output.
+		     *
+		     * To fix this properly we'll need some sort of
+		     * multi-page support in the SVG backend I think.
+		     */
 		    cairo_surface_set_fallback_resolution (surface, ppi[0], ppi[0]);
 		    cairo_show_page (cr);
 		}