Commit 6aff9afc authored by Carl Worth's avatar Carl Worth
Browse files

Remove pixman from SNAPSHOT_0_5_1

parents 5de154bc 86869f02
Cairo coding style.
This document is intended to be a short description of the preferred
coding style for the cairo source code. Good style requires good
taste, which means this can't all be reduced to automated rules, and
there are exceptions.
We want the code to be easy to understand and maintain, and consistent
style plays an important part in that, even if some of the specific
details seem trivial. If nothing else, this document gives a place to
put consistent answers for issues that would otherwise be arbitrary.
Most of the guidelines here are demonstrated by examples, (which means
this document is quicker to read than it might appear given its
length). Most of the examples are positive examples that you should
imitate. The few negative examples are clearly marked with a comment
of /* Yuck! */. Please don't submit code to cairo that looks like any
of these.
Indentation
-----------
Each new level is indented 4 more spaces than the previous level:
if (condition)
do_something ();
Spaces or tabs (or a combination) can be used in indentation, but tabs
must always be interpreted as 8 spaces. Code using single tabs for all
indentation (expecting people to interpret tabs as 4 spaces) will not
be accepted in cairo.
The rationale here is that tabs are used in the code for lining things
up other than indentation, (see the Whitespace section below), and
changing the interpretation of tab from 8 characters will break this.
Braces
------
Most of the code in cairo uses bracing in the style of K&R:
if (condition) {
do_this ();
do_that ();
} else {
do_the_other ();
}
but some of the code uses an alternate style:
if (condition)
{
do_this ();
do_that ();
}
else
{
do_the_other ();
}
and that seems just fine. We won't lay down any strict rule on this
point, (though there should be some local). If you came here hoping to
find some guidance, then use the first form above.
If all of the substatements of an if statement are single statements,
the optional braces should not usually appear:
if (condition)
do_this ();
else
do_that ();
But the braces are mandatory when mixing single statement and compound
statements in the various clauses. For example, do not do this:
if (condition) {
do_this ();
do_that ();
} else /* Yuck! */
do_the_other ();
And of course, there are exceptions for when the code just looks
better with the braces:
if (condition) {
/* Note that we have to be careful here. */
do_something_dangerous (with_care);
}
if (condition &&
other_condition &&
yet_another)
{
do_something ();
}
And note that this last example also shows a situation in which the
opening brace really needs to be on its own line. The following looks awful:
if (condition &&
other_condition &&
yet_another) { /* Yuck! */
do_something ();
}
As we said above, legible code that is easy to understand and maintain
is the goal, not adherence to strict rules.
Whitespace
----------
Separate logically distinct chunks with a single newline. This
obviously applies between functions, but also applies within a
function or block and can even be used to good effect within a
structure definition:
struct _cairo_gstate {
cairo_operator_t operator;
double tolerance;
/* stroke style */
double line_width;
cairo_line_cap_t line_cap;
cairo_line_join_t line_join;
double miter_limit;
cairo_fill_rule_t fill_rule;
double *dash;
int num_dashes;
double dash_offset;
...
}
Use a single space before a left parenthesis, except where the
standard will not allow it, (eg. when defining a parameterized macro).
Don't eliminate whitespace just because things would still fit on one
line. This breaks the expected visual structure of the code making it
much harder to read and understand:
if (condition) foo (); else bar (); /* Yuck! */
As a special case of the bracing and whitespace guidelines, function
definitions should always take the following form:
void
my_function (argument)
{
do_my_things ();
}
And function prototypes should similarly have the return type (and
associated specifiers and qualifiers) on a line above the function, so
that the function name is flush left.
Break up long lines (> ~80 characters) and use whitespace to align
things nicely. For example the arguments in a long list to a function
call should all be aligned with each other:
align_function_arguments (argument_the_first,
argument_the_second,
argument_the_third);
And as a special rule, in a function prototype, (as well as in the
definition), whitespace should be inserted between the parameter types
and names so that the names are aligned:
void
align_parameter_names_in_prototypes (const char *char_star_arg,
int int_arg,
double *double_star_arg,
double double_arg);
Note that parameters with a * prefix are aligned one character to the
left so that the actual names are aligned.
Managing nested blocks
----------------------
Long blocks that are deeply nested make the code very hard to
read. Fortunately such blocks often indicate logically distinct chunks
of functionality that are begging to be split into their own
functions. Please listen to the blocks when they beg.
In other cases, gratuitous nesting comes about because the primary
functionality gets buried in a nested block rather than living at the
primary level where it belongs. Consider the following:
foo = malloc (sizeof (foo_t));
if (foo) { /* Yuck! */
...
/* lots of code to initialize foo */
...
return SUCCESS;
}
return FAILURE;
This kind of gratuitous nesting can be avoided by following a pattern
of handling exceptional cases early and returning:
foo = malloc (sizeof (foo_t));
if (foo == NULL)
return FAILURE;
...
/* lots of code to initialize foo */
...
return SUCCESS;
The return statement is often the best thing to use in a pattern like
this. If it's not available due to additional nesting above which
require some cleanup after the current block, then consider splitting
the current block into a new function before using goto.
This diff is collapsed.
......@@ -9,6 +9,8 @@ EXTRA_DIST = \
pkgconfigdir = $(libdir)/pkgconfig
pkgconfig_DATA = cairo.pc
DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc
# Some custom targets to make it easier to release things.
# Use either:
# make release-check
......
Snapshot 0.5.1 (2005-06-20 Carl Worth <cworth@cworth.org>)
==========================================================
API changes
-----------
* Removed cairo_status_string(cairo_t*) and add
cairo_status_to_string(cairo_status_t) in its place. Code using
cairo_status_string can be ported forward as follows:
cairo_status (cr);
->
cairo_status_to_string (cairo_status (cr));
* Removed the BAD_NESTING restriction which means that two different
cairo_t objects can now interleave drawing to the same
cairo_surface_t without causing an error.
* The following functions which previously had a return type of
cairo_status_t now have a return type of void:
cairo_pattern_add_color_stop_rgba
cairo_pattern_set_matrix
cairo_pattern_get_matrix
cairo_pattern_set_extend
cairo_pattern_set_filter
See discussion of cairo_pattern_status below for more details.
API additions
-------------
* Improved error handling:
cairo_status_t
cairo_pattern_status (cairo_pattern_t *pattern);
This snapshot expands the status-based error handling scheme from
cairo_t to cairo_path_t and cairo_pattern_t. It also expands the
scheme so that object-creating functions, (cairo_create,
cairo_pattern_create_*, cairo_copy_path_*), are now guaranteed to
not return NULL. Instead, in the case of out-of-memory these
functions will return a static object with
status==CAIRO_STATUS_NO_MEMORY. The status can be checked with the
functions cairo_status and cairo_pattern_status, or by direct
inspection of the new status field in cairo_path_t.
Please note that some objects, including cairo_surface_t and all of
the font-related objects have not been converted to this
error-handling scheme.
* In addition to the above changes, a new private function has been added:
_cairo_error
This function can be used to set a breakpoint in a debugger to make
it easier to find programming error in cairo-using code. (Currently,
_cairo_error is called when any error is detected within a cairo_t
context, but is not called for non-cairo_t errors such as for
cairo_path_t and cairo_pattern_t).
* Fixed cairo_path_data_t so that its enum is visible to C++ code, (as
cairo_path_data_type_t).
Performance improvements
------------------------
* Made a minor performance improvement for clipping, (restrict clip
surface to the new intersected bounds).
* Optimize rendering of a solid source pattern with a pixel-aligned
rectangular path to use backend clipping rather than rasterization
and backend compositing.
* Optimize cairo_paint_with_alpha to defer to cairo_paint when alpha
is 1.0.
Bug fixes
---------
* Fixed memory leak in cairo_copy_path.
* A build fix for non-srcdir builds.
PDF backend fixes
-----------------
* New support for path-based clipping.
* Fix for text rotated to angles other than multiples of π/2.
Win32 backend fixes
-------------------
* Fix for text extents.
Xlib backend
------------
* Implemented a complex workaround for X server bug[*] related to
Render-based compositing with untransformed, repeating source
pictures. The workaround uses core Xlib when possible for
performance, (ie. with CAIRO_OPERATOR_SOURCE or CAIRO_OPERATOR_OVER
with an opaque source surface), and falls back to the pixman
image-based compositing otherwise.
[*] https://bugs.freedesktop.org/show_bug.cgi?id=3566
* Various bug fixes, particularly in the fallback paths.
Snapshot 0.5.0 (2005-05-17 Carl Worth <cworth@cworth.org>)
==========================================================
This is a pretty big, and fairly significant snapshot. It represents
......
......@@ -69,6 +69,12 @@ API Issues (more detail in TODO file)
of them.
Status: not started, there is a rough plan in TODO
A9. consistent error handling for all objects
Difficulty: Easy to implement to get the API right. Hard to test.
Status: Done for cairo_t, cairo_path_t, and cairo_pattern_t.
Still need to do cairo_font_face_t,
cairo_scaled_font_t, and cairo_surface_t.
Performance work
----------------
✓P1. Make pixel-aligned rectangle compositing fast
......
API Shakeup planning
--------------------
Changes that are expected to impact the public API
==================================================
Patch submitted to mailing list?
/ Documentation included in patch?
|/ Review of patch completed?
||/ Test case included?
|||/ Committed.
||||/
New functionality (more-or-less)
--------------------------------
Backwards compatible (API additions only)
-----------------------------------------
cairo_begin_group, cairo_end_group, cairo_get_group
cairo_<device>_surface_mark_dirty
Consistent error handling for all objects
Somewhat backwards-compatible changes
-----------------------------------
PDRTC user data (was Re: [cairo] Patch improving fallbacks)
PDRTC setters and getters
PDRTC cairo_output_stream_t and cairo_surface_finish()
PDRTC cairo_current_path -> cairo_copy_path_data
cairo_surface_mark_dirty (see below for details)
Add support for non-antialiased rendering. API ?
Add CAIRO_FILL_RULE_INVERSE_WINDING and CAIRO_FILL_RULE_INVERSE_EVEN_ODD
Add cairo_text_glyphs (see below for details)
Add support for programmatic patterns, (ie. arbitrary gradients)
Add cairo_arc_to.
Add support for custom caps (see below for details)
Add support for getting at image data from image surface
Add CAIRO_STATUS_DESTROYED
Add cairo_finish
Backwards incompatible (API deletions or changes)
-------------------------------------------------
PDR C cairo_surface_finish, cairo_surface_flush
PDRTC Abbreviation hunt: cairo_init_clip and cairo_concat_matrix
PDRTC Renaming the terms of the rendering equation
PDRTC default matrix
PDRTC cairo_paint
PDRTC Making set_source consistent
PDRTC cairo_stroke_path -> cairo_stroke_to_path
PDRTC cairo_current_matrix
PDRTC cairo_mask
PDRTC cairo_fill_preserve, cairo_stroke_preserve, cairo_clip_preserve
PDR C A hidden offset for the xlib backend
P Consistent error handling for all objects
Split cairo_format_t (see below for details)
P---C Remove cairo_status_string in favor of cairo_status_to_string
Backwards incompatible
----------------------
PDRTC Simplifying the operator set
PDRTC cairo_create and eliminating cairo_set_target_surface
PDRTC Eliminating cairo_copy
PDRTC Eliminating cairo_surface_set_repeat/matrix/filter
PDRTC Eliminating cairo_show_surface
Details on some of the above changes
------------------------------------
* cairo_surface_mark_dirty
* Add support for non-antialiased rendering. API ?
One question is what the function should accept. A single
device-space rectangle seems like a consistent approach. That would
allow us to avoid needing backend-specific functions with
backend-specific region datatypes, (cf. clipping support)
* Clean up the cache code a bit, (there is at least one redundant
level of cacheing, and there are some minor style issues).
In order to get the intended efficiency benefits, we'll need to make
two changes:
* Add CAIRO_FILL_RULE_INVERSE_WINDING and CAIRO_FILL_RULE_INVERSE_EVEN_ODD
1) In the fallback code, never fetch any data from the clean
region.
* Fix clipping to work for all operators. The equation we have come up
with is:
2) Mark clean any region drawn with device-pixel aligned
rectangles, (cairo_paint with no clip is the most iportant
one here).
((src Op dest) In clip) Add (dest Out clip)
* cairo_text_glyphs:
It would function as a sort of bridge between the toy and the
real text APIs:
> void
> cairo_text_glyphs (cairo_t *cr, const unsigned char *utf8,
> cairo_glyph_t *glyphs, int *num_glyphs);
>
> with num_glyphs as an input-output parameter. The behavior of this
> function would be such that calling:
>
> cairo_text_glyphs (cr, string, glyphs, &num_glyphs);
> cairo_show_glyphs (cr, glyphs, num_glyphs);
>
> would be equivalent too:
>
> cairo_show_text (cr, string);
>
> as long as the original size of glyphs/num_glyphs was large
> enough.
* support for custom caps:
It would be nice if the user had a mechanism to reliably draw custom
caps. One approach here would be to provide the coordinates of the
butt cap faces so that the user can append seamless caps to the
current path. We may also need to provide the coordinates of the
faces of every dash as well.
* Split cairo_format_t into two things:
* split cairo_format_t into two things:
- An enumeration that determines the "capabilities" of a surface -
A vs. ARGB. vs. RGB
......@@ -82,92 +110,32 @@ PDRTC Eliminating cairo_show_surface
people are going to screw up and pass CAIRO_FORMAT_RGB into that, and if it
"just worked" that would save people trouble....)
* Clean up the API in preparation for freezing and release.
Changes that do not affect the public API
=========================================
* Clean up the cache code a bit, (there is at least one redundant
level of cacheing, and there are some minor style issues).
* Make a more interesting PS backend, (other than the current
"giant-image for every page" approach).
* Fix clipping to work for all operators. The equation we have come up
with is:
((src Op dest) In clip) Add (dest Out clip)
* Figure out what to do with DPI for image/png backends.
* Make a more interesting PS backend, (other than the current
"giant-image for every page" approach).
* Change stroke code to go through one giant polygon. This will fix
problems with stroking self-intersecting paths.
* Re-work the backend clipping interface to use geometry rather than
images.
problems with stroking self-intersecting paths.
* Fix the intersection problem, (see reference to Hobby's paper
mentioned in cairo_traps.c).
* Add a new cairo_text_glyphs function (a sort of bridge between the
toy and the real text API):
> void
> cairo_text_glyphs (cairo_t *cr, const unsigned char *utf8,
> cairo_glyph_t *glyphs, int *num_glyphs);
>
> with num_glyphs as an input-output parameter. The behavior of this
> function would be such that calling:
>
> cairo_text_glyphs (cr, string, glyphs, &num_glyphs);
> cairo_show_glyphs (cr, glyphs, num_glyphs);
>
> would be equivalent too:
>
> cairo_show_text (cr, string);
>
> as long as the original size of glyphs/num_glyphs was large
> enough.
mentioned in cairo_traps.c).
* Implement dashing for cairo_curve_to.
* Implement support for programmatic patterns, (ie. figure out how to
do gradients the Right Way).
* Implement cairo_arc_to.
* Stroking closed, degenerate paths should still draw caps. Round
caps are easy; square should probably draw an axis-aligned square.
* It would be nice if the user had a mechanism to reliably draw custom
caps. One approach here would be to provide the coordinates of the
butt cap faces so that the user can append seamless caps to the
current path. We may also need to provide the coordinates of the
faces of every dash as well.
* Should add geometry pruning as appropriate.
* We need a way to get at the image data after something
like cairo_surface_create_similar with the image backend.
* Three suggestions from Owen that will help GTK+ performance:
- The ability have an additional rectangle-list clip in the
Xlib surface. Frequently during an expose event, GTK+ is
drawing L shaped areas
XXXXXX
X.....
X.....
And passing the real clip to the server is going to save
a lot of pixel operations that will be thrown away.
- The ability to pass in a width/height to cairo_xlib_surface_create()
to avoid a round-trip. (Round-trips are bad to the point where
querying the the server is something you don't want to do in
production software)
- More of a future thing, the ability to hint to to cairo that
the contents of the Xlib surface passed to
cairo_xlib_surface_create() are a solid fill ... this is
very much the normal case for GTK+ usage and allows for
big optimization in the no-RENDER case.
(see http://mail.gnome.org/archives/gtk-devel-list/2003-March/msg00045.html
* Verification, profiling, optimization.
centi_unfinished.svg may provide a good test case.
* Implement copy-on-write regions in pixman as a more complete
solution than the BAD_NESTING stuff to Owen's "Clip region problems"
thread.
......@@ -5,7 +5,7 @@ AC_INIT(src/cairo.h)
dnl ===========================================================================
# Package version number, (as distinct from shared library version)
CAIRO_VERSION=0.5.0
CAIRO_VERSION=0.5.1
# libtool shared library version
......
......@@ -3,6 +3,7 @@ Makefile
Makefile.in
cairo-decl-list.txt
cairo-decl.txt
cairo-docs.sgml
cairo-undocumented.txt
cairo-unused.txt
cairo.hierarchy
......@@ -13,3 +14,5 @@ cairo.signals
html
xml
......@@ -38,6 +38,9 @@ GTKDOC_LIBS =
# Extra options to supply to gtkdoc-mkdb
MKDB_OPTIONS=--sgml-mode --output-format=xml
# Extra options to supply to gtkdoc-mktmpl
MKTMPL_OPTIONS=
# Non-autogenerated SGML files to be included in $(DOC_MAIN_SGML_FILE)
content_files = \
language-bindings.xml
......
<SECTION>
<FILE>cairo-atsui</FILE>
<TITLE>ATSUI Fonts</TITLE>
cairo_atsui_font_create
</SECTION>
<SECTION>
<FILE>cairo-ft</FILE>
<TITLE>FreeType Fonts</TITLE>
......@@ -23,7 +17,8 @@ cairo_glitz_surface_create
<FILE>cairo-pdf</FILE>
<TITLE>PDF Backend</TITLE>
cairo_pdf_surface_create
cairo_pdf_surface_create_for_callback
cairo_pdf_surface_create_for_stream
cairo_pdf_surface_set_dpi
</SECTION>
<SECTION>
......@@ -39,6 +34,8 @@ cairo_surface_write_to_png_stream
<FILE>cairo-ps</FILE>
<TITLE>PS Backend</TITLE>
cairo_ps_surface_create
cairo_ps_surface_create_for_stream
cairo_ps_surface_set_dpi
</SECTION>
<SECTION>
......@@ -61,30 +58,38 @@ cairo_win32_scaled_font_get_metrics_factor
<FILE>cairo-xcb</FILE>
<TITLE>XCB Backend</TITLE>
cairo_xcb_surface_create
cairo_xcb_surface_create_for_bitmap
cairo_xcb_surface_set_size
</SECTION>
<SECTION>
<FILE>cairo-xcb-xrender</FILE>
<TITLE>XCB Backend</TITLE>
cairo_xcb_surface_create_with_xrender_format
</SECTION>
<SECTION>
<FILE>cairo-xlib</FILE>
<TITLE>XLib Backend</TITLE>
cairo_xlib_surface_create
cairo_xlib_surface_create_with_visual
cairo_xlib_surface_create_for_bitmap
cairo_xlib_surface_set_size
</SECTION>
<SECTION>
<FILE>cairo-xlib-xrender</FILE>
<TITLE>XLib/Xrender Backend</TITLE>
cairo_xlib_surface_create_with_xrender_format
</SECTION>
<SECTION>
<FILE>cairo-surface</FILE>