Handling clip as part of the surface state, as opposed to being part of
the operation state, is cumbersome and a hindrance to providing true proxy
surface support. For example, the clip must be copied from the surface
onto the fallback image, but this was forgotten causing undue hassle in
each backend. Another example is the contortion the meta surface
endures to ensure the clip is correctly recorded. By contrast passing the
clip along with the operation is quite simple and enables us to write
generic handlers for providing surface wrappers. (And in the future, we
should be able to write more esoteric wrappers, e.g. automatic 2x FSAA,
trivially.)
In brief, instead of the surface automatically applying the clip before
calling the backend, the backend can call into a generic helper to apply
clipping. For raster surfaces, clip regions are handled automatically as
part of the composite interface. For vector surfaces, a clip helper is
introduced to replay and callback into an intersect_clip_path() function
as necessary.
Whilst this is not primarily a performance related change (the change
should just move the computation of the clip from the moment it is applied
by the user to the moment it is required by the backend), it is important
to track any potential regression:
ppc:
Speedups
========
image-rgba evolution-20090607-0 1026085.22 0.18% -> 672972.07 0.77%: 1.52x speedup
▌
image-rgba evolution-20090618-0 680579.98 0.12% -> 573237.66 0.16%: 1.19x speedup
▎
image-rgba swfdec-fill-rate-4xaa-0 460296.92 0.36% -> 407464.63 0.42%: 1.13x speedup
▏
image-rgba swfdec-fill-rate-2xaa-0 128431.95 0.47% -> 115051.86 0.42%: 1.12x speedup
▏
Slowdowns
=========
image-rgba firefox-periodic-table-0 56837.61 0.78% -> 66055.17 3.20%: 1.09x slowdown
▏
Joonas reported that adding the extra routines to the null-surface as used
by the analysis surface broke user-fonts. So create a separate null
backend to be exported via the test-null surface.
Using a null surface is a convenient method to measure the overhead of the
performance testing framework, so export it although as a test-surface so
that it will only be available in development builds and not pollute
distributed libraries.
Avoid secondary allocations of the thin region wrappers during surface
creation by embedding them into the parent structure. This has the
satisfactory side-effect of not requiring status checks which current code
lacks.
Specifically,
cairo_region_union_rect -> cairo_region_union_rectangle
cairo_region_create_rect -> cairo_region_create_rectangle
Also delete cairo_region_clear() which is not that useful.
Rename approximate_extents() to approximate_clip_extents() so that it is
consistent with the fill and stroke variants and clearer under what
circumstances you may wish to use it.
With Behdad's analytical analysis of the spline bbox, tolerance is now
redundant for the path extents and the approximate bounds, so remove it
from the functions parameters.
Based on feedback from Jeff Muizelaar, there is a case for a very quick
and dirty extents approximation based solely on the curve control points
(for example when computing the clip intersect rectangle of a path) and
by moving the stroke extension into a core function we can clean up the
interface for all users, and centralise the logic of approximating the
stroke extents.
When analysing the stroke extents, we need the original fixed-point
extents so that we do not incur an OBO when we round-to-integer a second
time. We also need a more accurate estimate than simply using the control
points of the curve, so pass in tolerance and decompose until someone
discovers a cheaper algorithm to determine the precise aligned bounding
box of a bezier curve.
If we are dithering on the Xlib backend we can not simply repaint the
surface used for a solid pattern and must recreate it from scratch.
However, for ordinary XRender usage we do not want to have to pay that
price - so query the backend to see if we can reuse the surface.
A surface will have the chance to use span rendering at cairo_fill()
time by creating a renderer for a specific combination of
pattern/dst/op before the path is scan converted. The protocol is to
first call check_span_renderer() to see if the surface wants to render
with spans and then later call create_span_renderer() to create the
renderer for real once the extents of the path are known.
No backends have an implementation yet.
When computing the bounds of the clip path, we care more for a fast result
than absolute precision as the extents are only used as a guide to trim
the future operations. So computing the extents of the path suffices.
To be able to provide the extents of each operation to the backend
during the render phase the meta-surface needs to store the extents
computed by the analysis surface during the analysis phase.
The extents argument is either a pointer to the extents of the operation
stored in the meta-surface or NULL. During analysis the analysis surface
writes the extents to the meta-surface. During the render phase the extents
is made available to paginated surface backends.
Add a "cairo_rectangle_int_t *extents" argument to to the following
backend functions:
paint
mask,
stroke
fill
show_glyphs
show_text_glyphs
This will be used to pass the extents of each operation computed by
the analysis surface to the backend. This is required for implementing
EXTEND_PAD.
Only copy the pattern if we need to modify it, e.g. preserve a copy in a
snapshot or a soft-mask, or to modify the matrix. Otherwise we can
continue to use the original pattern and mark it as const in order to
generate compiler warnings if we do attempt to write to it.
Adrian Johnson discovered cases where we mistakenly compared the result
of unsigned arithmetic where we need signed quantities. Look for similar
cases in the users of cairo_rectangle_int_t.
Since there is an implicit precedence in the ranking of the analysis
return codes, provide a function to centralize the logic within the
analysis surface and isolate the backends from the complexity.
The primary bug here was some missing braces. The code was conditionally
assigning to backend_status, but then unconditionally checking for the
value assigned. The result was the leaking of an internal status value
(CAIRO_INT_STATUS_ANALYZE_META_SURFACE) which finally resulted in
an incomplete PDF file in the mask-transformed-similar test case.
While fixing this, also avoid re-using the backend_status variable so
much so that the code is more readable.
Since these functions are static we don't really need the full
name. And these two functions were both so long that they were
causing some serious line-wrap issues.
Use the utility functions _cairo_box_from_rectangle and
_cairo_box_round_to_rectangle() instead of open-coding. Simultaneously
tweak the whitespace so that all users of traps look similar.
Chris rightfully complained that having a boolean function argument is
new in cairo_show_text_glyphs, and indeed avoiding them has been one
of the API design criteria for cairo. Trying to come up with alternatives,
Owen suggested using a flag type which nicely solves the problem AND
future-proofs such a complex API.
Please welcome _flags_t APIs to cairo.h
We added cairo_has_show_text_glyphs() before. Since this is really a
surface property, should have the surface method too. Like we added
cairo_surface_show_page()...
This is needed because analysis-surface takes any UNSUPPORTED returns
as a signal for using image fallbacks. So the fallback mechanism in
_cairo_surface_show_text_glyphs() is not enough. Reported by Adrian
Johnson.
Originally reported here:
http://lists.cairographics.org/archives/cairo/2008-May/014032.html
and analyized later in the thread.
Change (font and surface) backend show_glyphs() API to take a
int *remaining_glyphs argument. It's used to communicate to the caller,
by way of setting remaining_glyphs and returning INT_STATUS_UNSUPPORTED,
that some of the glyphs were shown but not the others. The xlib backend
now correctly uses this to handle failure to upload a glyph to the server.
So the large-font test passes now.
An alternative approach could be to add some public value for glyphs
indices that are not shown. -1 perhaps (the xlib backend already uses
that value internally). Then instead of remaining_glyphs, a backend
could simply set glyph indices of glyphs shown to that -1 value.
It creates a surface that does nothing. This can be used with
cairo-analysis-surface, to compute bounds of cairo drawings without doing any
actual drawings.
If during analysis the bounding box of an operation or the number of
traps is 0, the operation is marked as natively supported. The problem
here is if the operation is unsupported by the backend, we get an
assertion when the operation is replayed during
CAIRO_PAGINATED_MODE_RENDER.
This bug was found in Inkscape when printing to the
win32_printing_surface a page that has been layed out as landscape but
landscape paper had not been selected in the print dialog.
Fix this by being careful not to mark unsupported operations as
supported during analysis even they may not be visible on the page.
I was wrong in my assertion that the call to
_cairo_path_fixed_interpret_flat() could not possibly fail with the
given _cairo_path_bounder_* callbacks - as I had missed the implicit
spline decomposition. (An interesting exercise would be to avoid the
spline allocation...) As a result we do have to check and propagate the
status return through the call stack.
The surface size and clip needs to be saved before and restored after
replaying meta surface patterns back to the analysis surface. The clip
is reset and the correct surface size is set before replaying the meta
surface.
cairo_rectangle_int16_t was being used in a number of places instead
of cairo_rectangle_int_t, which led to memory corruption when cairo was
using a fixed point format with a bigger space than 16.16 (such as 24.8).
_cairo_path_fixed_bounds can use the new _interpret_flat mechanism; this
results in tighter bounds; previously the bounds followed the control
points of the beziers, whereas now they are the bounds of the curve.
