[cairo] On cairo_set_tolerance() and PS/PDF backends

[Behdad Esfahbod]

Hi,

This has been discussed multiple times before.  It most recently surfaced on:
http://bugs.freedesktop.org/show_bug.cgi?id=23364

I like to propose changing the semantics, and hence, documentation of 
cairo_set_tolerance(), from:

"Sets the tolerance used when converting paths into trapezoids. Curved 
segments of the path will be subdivided until the maximum deviation between 
the original path and the polygonal approximation is less than tolerance."

to:

"Sets the error tolerance of cairo's output in device space.  Generated 
graphics will not deviate from the user's expressed graphics more than 
tolerance.  A higher value results in more fidelity, but will be slower and 
may generate larger output file size (for file-based backends)."

Pretty straightforward and reasonable extension, right?

With this change we can optimize the PS/PDF outputs considerably.  For example:

   1. Painting a huge image (say, 2000x2000 pixels) into a small area (say, 
1x1 inch) currently embeds all the pixel data, which is more often than not 
wasteful.  We can use the tolerance to shrink the embedded image.

   2. It can be used to decide how many digits to use for float numbers. 
Adrian says in bug 23364:

"""
Using a tolerance in device units does not make sense for all the floating
point values emitted by the PDF backend. For example in PDF floats are used
for:

  - coordinates
  - colors
  - Td operator for text
  - pattern matrices
  - function domains

Coordinates are already limited to 3 decimal places due to the use of
24.8 fixed point.

Controlling the precision of colors is not possible with a parameter in device
units. Users may wish to control the precision of color independently of
coordinates.

Neither does it make sense to use a value in device units to control the
precision of values in pattern matrices. These should be set using number of
significant figures.
"""

Sure, I'm not saying tolerance should be used for color numbers.  That's 
nonsense.  But it can be used for all the different coordinate numbers.  With 
proper space conversion of course.  All we need is to scale the tolerance 
value by the largest eigenvalue.

That's indeed what my patch in 7f21bfb0a8 did for a similar case.  That patch 
however was reverted since Adrian at the time argued that tolerance is in the 
physical device space (your printer's), not cairo device space (72dpi for 
PDF).  However, IMO that definition is bogus.

Anyway, that's the gist of it.

behdad