[cairo-commit] 7 commits - README src/cairo.c src/cairo.h src/cairoint.h src/cairo-pattern.c src/cairo-surface.c
Carl Worth
cworth at kemper.freedesktop.org
Sun Apr 6 02:48:09 PDT 2008
README | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++
src/cairo-pattern.c | 3 +
src/cairo-surface.c | 3 +
src/cairo.c | 62 +++++++++++++++++++++----
src/cairo.h | 25 +++++++---
src/cairoint.h | 2
6 files changed, 206 insertions(+), 17 deletions(-)
New commits:
commit e07e1b7bbbac59ae2ea25ed762c017b477e22cc4
Author: Carl Worth <cworth at cworth.org>
Date: Sun Apr 6 02:47:32 2008 -0700
Document many more defaults
Including: fallback_resolution, fill_rule, line_cap, line_join,
miter_limit, font_face, font_size, and operator.
diff --git a/src/cairo-surface.c b/src/cairo-surface.c
index a724283..12b0885 100644
--- a/src/cairo-surface.c
+++ b/src/cairo-surface.c
@@ -887,6 +887,9 @@ slim_hidden_def (cairo_surface_get_device_offset);
* there is currently no way to have more than one fallback resolution
* in effect on a single page.
*
+ * The default fallback resoultion is 300 pixels per inch in both
+ * dimensions.
+ *
* Since: 1.2
**/
void
diff --git a/src/cairo.c b/src/cairo.c
index f6404df..bb943da 100644
--- a/src/cairo.c
+++ b/src/cairo.c
@@ -634,9 +634,7 @@ slim_hidden_def(cairo_pop_group_to_source);
* operations. See #cairo_operator_t for details on the semantics of
* each available compositing operator.
*
- * XXX: I'd also like to direct the reader's attention to some
- * (not-yet-written) section on cairo's imaging model. How would I do
- * that if such a section existed? (cworth).
+ * The default operator is %CAIRO_OPERATOR_OVER.
**/
void
cairo_set_operator (cairo_t *cr, cairo_operator_t op)
@@ -891,6 +889,8 @@ cairo_set_antialias (cairo_t *cr, cairo_antialias_t antialias)
* (potentially self-intersecting) path. The current fill rule affects
* both cairo_fill() and cairo_clip(). See #cairo_fill_rule_t for details
* on the semantics of each available fill rule.
+ *
+ * The default fill rule is %CAIRO_FILL_RULE_WINDING.
**/
void
cairo_set_fill_rule (cairo_t *cr, cairo_fill_rule_t fill_rule)
@@ -959,6 +959,8 @@ cairo_set_line_width (cairo_t *cr, double width)
* examined by cairo_stroke(), cairo_stroke_extents(), and
* cairo_stroke_to_path(), but does not have any effect during path
* construction.
+ *
+ * The default line cap style is %CAIRO_LINE_CAP_BUTT.
**/
void
cairo_set_line_cap (cairo_t *cr, cairo_line_cap_t line_cap)
@@ -976,7 +978,7 @@ cairo_set_line_cap (cairo_t *cr, cairo_line_cap_t line_cap)
/**
* cairo_set_line_join:
* @cr: a cairo context
- * @line_join: a line joint style
+ * @line_join: a line join style
*
* Sets the current line join style within the cairo context. See
* #cairo_line_join_t for details about how the available line join
@@ -986,6 +988,8 @@ cairo_set_line_cap (cairo_t *cr, cairo_line_cap_t line_cap)
* examined by cairo_stroke(), cairo_stroke_extents(), and
* cairo_stroke_to_path(), but does not have any effect during path
* construction.
+ *
+ * The default line join style is %CAIRO_LINE_JOIN_MITER.
**/
void
cairo_set_line_join (cairo_t *cr, cairo_line_join_t line_join)
@@ -1116,6 +1120,15 @@ cairo_get_dash (cairo_t *cr,
* examined by cairo_stroke(), cairo_stroke_extents(), and
* cairo_stroke_to_path(), but does not have any effect during path
* construction.
+ *
+ * The default miter limit value is 10.0, which will convert joins
+ * with interior angles less than 11 degrees to bevels instead of
+ * miters. For reference, a miter limit of 2.0 makes the miter cutoff
+ * at 60 degrees, and a miter limit of 1.414 makes the cutoff at 90
+ * degrees.
+ *
+ * A miter limit for a desired angle can be computed as: miter limit =
+ * 1/sin(angle/2)
**/
void
cairo_set_miter_limit (cairo_t *cr, double limit)
@@ -2598,6 +2611,11 @@ cairo_copy_clip_rectangle_list (cairo_t *cr)
* It is expected that most applications will need to use a more
* comprehensive font handling and text layout library, (for example,
* pango), in conjunction with cairo.
+ *
+ * If text is drawn without a call to cairo_select_font_face(), (nor
+ * cairo_set_font_face() nor cairo_set_scaled_font()), the default
+ * family is "sans", slant is %CAIRO_FONT_SLANT_NORMAL, and weight is
+ * %CAIRO_FONT_WEIGHT_NORMAL.
**/
void
cairo_select_font_face (cairo_t *cr,
@@ -2712,6 +2730,10 @@ cairo_get_font_face (cairo_t *cr)
* cairo_set_font_matrix(). This results in a font size of @size user space
* units. (More precisely, this matrix will result in the font's
* em-square being a @size by @size square in user space.)
+ *
+ * If text is drawn without a call to cairo_set_font_size(), (nor
+ * cairo_set_font_matrix() nor cairo_set_scaled_font()), the default
+ * font size is 10.0.
**/
void
cairo_set_font_size (cairo_t *cr, double size)
diff --git a/src/cairo.h b/src/cairo.h
index 560178b..4a3a773 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -373,6 +373,8 @@ cairo_pop_group_to_source (cairo_t *cr);
* #cairo_operator_t is used to set the compositing operator for all cairo
* drawing operations.
*
+ * The default operator is %CAIRO_OPERATOR_OVER.
+ *
* The operators marked as <firstterm>unbounded</firstterm> modify their
* destination even outside of the mask layer (that is, their effect is not
* bound by the mask layer). However, their effect can still be limited by
@@ -473,6 +475,8 @@ cairo_set_antialias (cairo_t *cr, cairo_antialias_t antialias);
* (Note that filling is not actually implemented in this way. This
* is just a description of the rule that is applied.)
*
+ * The default fill rule is %CAIRO_FILL_RULE_WINDING.
+ *
* New entries may be added in future versions.
**/
typedef enum _cairo_fill_rule {
@@ -492,7 +496,9 @@ cairo_set_line_width (cairo_t *cr, double width);
* @CAIRO_LINE_CAP_ROUND: use a round ending, the center of the circle is the end point
* @CAIRO_LINE_CAP_SQUARE: use squared ending, the center of the square is the end point
*
- * Specifies how to render the endpoint of a line when stroking.
+ * Specifies how to render the endpoints of the path when stroking.
+ *
+ * The default line cap style is %CAIRO_LINE_CAP_BUTT.
**/
typedef enum _cairo_line_cap {
CAIRO_LINE_CAP_BUTT,
@@ -513,6 +519,8 @@ cairo_set_line_cap (cairo_t *cr, cairo_line_cap_t line_cap);
* the line width from the joint point
*
* Specifies how to render the junction of two lines when stroking.
+ *
+ * The default line join style is %CAIRO_LINE_JOIN_MITER.
**/
typedef enum _cairo_line_join {
CAIRO_LINE_JOIN_MITER,
commit a55669c325c341fa6175a193cb0d6fa30b8247c9
Author: Carl Worth <cworth at cworth.org>
Date: Sun Apr 6 02:17:33 2008 -0700
Document toy nature of cairo_select_font_face
diff --git a/src/cairo.c b/src/cairo.c
index b540af3..f6404df 100644
--- a/src/cairo.c
+++ b/src/cairo.c
@@ -2571,13 +2571,33 @@ cairo_copy_clip_rectangle_list (cairo_t *cr)
* @slant: the slant for the font
* @weight: the weight for the font
*
+ * Note: The cairo_select_font_face() function call is part of what
+ * the cairo designers call the "toy" text API. It is convenient for
+ * short demos and simple programs, but it is not expected to be
+ * adequate for serious text-using applications.
+ *
* Selects a family and style of font from a simplified description as
- * a family name, slant and weight. This function is meant to be used
- * only for applications with simple font needs: Cairo doesn't provide
- * for operations such as listing all available fonts on the system,
- * and it is expected that most applications will need to use a more
- * comprehensive font handling and text layout library in addition to
- * cairo.
+ * a family name, slant and weight. Cairo provides no operation to
+ * list available family names on the system (this is a "toy",
+ * remember"), but the standard CSS2 generic family names, ("serif",
+ * "sans-serif", "cursive", "fantasy", "monospace"), are likely to
+ * work as expected.
+ *
+ * For "real" font selection, see the font-backend-specific
+ * font_face_create functions for the font backend you are using. (For
+ * example, if you are using the freetype-based cairo-ft font backend,
+ * see cairo_ft_font_face_create_for_ft_face() or
+ * cairo_ft_font_face_create_for_pattern().) The resulting font face
+ * could then be used with cairo_scaled_font_create and
+ * cairo_set_scaled_font().
+ *
+ * Similarly, when using the "real" font support, you can call
+ * directly into the underlying font system, (such as fontconfig or
+ * freetype), for operations such as listing available fonts, etc.
+ *
+ * It is expected that most applications will need to use a more
+ * comprehensive font handling and text layout library, (for example,
+ * pango), in conjunction with cairo.
**/
void
cairo_select_font_face (cairo_t *cr,
commit d1fe0084405a49f33d4ab6d80e9398e281483900
Author: Carl Worth <cworth at cworth.org>
Date: Sun Apr 6 02:17:09 2008 -0700
Document default extend modes
diff --git a/src/cairo-pattern.c b/src/cairo-pattern.c
index e1d4b5c..097fc39 100644
--- a/src/cairo-pattern.c
+++ b/src/cairo-pattern.c
@@ -1084,6 +1084,9 @@ cairo_pattern_get_filter (cairo_pattern_t *pattern)
* Sets the mode to be used for drawing outside the area of a pattern.
* See #cairo_extend_t for details on the semantics of each extend
* strategy.
+ *
+ * The default extend mode is %CAIRO_EXTEND_NONE for surface patterns
+ * and %CAIRO_EXTEND_PAD for gradient patterns.
**/
void
cairo_pattern_set_extend (cairo_pattern_t *pattern, cairo_extend_t extend)
diff --git a/src/cairo.h b/src/cairo.h
index 542a996..560178b 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -1794,8 +1794,13 @@ cairo_pattern_get_matrix (cairo_pattern_t *pattern,
* the closest pixel from the source (Since 1.2; but only
* implemented for surface patterns since 1.6)
*
- * #cairo_extend_t is used to describe how the area outside
- * of a pattern will be drawn.
+ * #cairo_extend_t is used to describe how pattern color/alpha will be
+ * determined for areas "outside" the pattern's natural area, (for
+ * example, outside the surface bounds or outside the gradient
+ * geometry).
+ *
+ * The default extend mode is %CAIRO_EXTEND_NONE for surface patterns
+ * and %CAIRO_EXTEND_PAD for gradient patterns.
*
* New entries may be added in future versions.
**/
commit abe6f9541eb1fe10c063540dbffe3499ec8a9d3e
Author: Carl Worth <cworth at cworth.org>
Date: Sun Apr 6 02:01:04 2008 -0700
Document EXTEND_REFLECT and EXTEND_PAD as implemented for surfaces since 1.6
diff --git a/src/cairo.h b/src/cairo.h
index ab730e7..542a996 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -1789,10 +1789,10 @@ cairo_pattern_get_matrix (cairo_pattern_t *pattern,
* are fully transparent
* @CAIRO_EXTEND_REPEAT: the pattern is tiled by repeating
* @CAIRO_EXTEND_REFLECT: the pattern is tiled by reflecting
- * at the edges (not implemented for surface patterns currently)
+ * at the edges (Implemented for surface patterns since 1.6)
* @CAIRO_EXTEND_PAD: pixels outside of the pattern copy
- * the closest pixel from the source (Since 1.2; not implemented
- * for surface patterns currently)
+ * the closest pixel from the source (Since 1.2; but only
+ * implemented for surface patterns since 1.6)
*
* #cairo_extend_t is used to describe how the area outside
* of a pattern will be drawn.
commit 657b348e0172f3b5f2c91a406c2eca039a790ca1
Author: Carl Worth <cworth at cworth.org>
Date: Sun Apr 6 01:57:45 2008 -0700
README: Update dependencies
diff --git a/README b/README
index 76b2c2b..efca44c 100644
--- a/README
+++ b/README
@@ -58,91 +58,130 @@ Roadmap and unscheduled things to do, (please feel free to help out):
Dependencies
============
The set of libraries needed to compile cairo depends on which backends
-are enabled when cairo is configured. Here are the dependencies for
-each backend:
+are enabled when cairo is configured. So look at the list below to
+determine which dependencies are needed for the backends of interest.
-Surface backends:
+For the surface backends, we have both "supported" and "experimental"
+backends. Further, the supported backends can be divided into the
+"standard" backends which can be easily built on any platform, and the
+"platform" backends which depend on some underlying platform-specific
+system, (such as the X Window System or some other window system).
+As an example, for a standard Linux build, (with image, png, pdf,
+PostScript, svg, and xlib surface backends, and the freetype font
+backend), the following sample commands will install necessary
+dependencies:
+
+ Debian (and similar):
+
+ apt-get install libpng12-dev libz-dev libxrender-dev libfontconfig1-dev
+
+ Fedora (and similar):
+
+ yum install libpng-devel zlib-devel libXrender-devel fontconfig-devel
+
+(Those commands intentionally don't install pixman from a distribution
+package since if you're manually compiling cairo, then you likely want
+to grab pixman from the same place at the same time and compile it as
+well.)
+
+Supported, "standard" surface backends
+------------------------------------
image backend (required)
------------------------
- pixman http://cairographics.org/releases
- or: git://git.cairographics.org/git/pixman
+ pixman >= 0.10.0 http://cairographics.org/releases
- glitz backend
- -------------
- glitz >= 0.4.4 http://freedesktop.org/Software/glitz
+ png support (can be left out if desired, but many
+ ----------- applications expect it to be present)
+ libpng http://www.libpng.org/pub/png/libpng.html
pdf backend
-----------
- freetype >= 2.1.4 http://freetype.org
zlib http://www.gzip.org/zlib
postscript backend
------------------
- freetype >= 2.1.4 http://freetype.org
zlib http://www.gzip.org/zlib
- quartz backend
- --------------
- [*]
-
- win32 backend
- -------------
- [*]
-
- xcb backend
+ svg backend
-----------
- XCB http://xcb.freedesktop.org
+ [none]
+Supported, "platform" surface backends
+-----------------------------------
xlib backend
------------
- Xrender >= 0.6 http://freedesktop.org/Software/xlibs
+ X11 http://freedesktop.org/Software/xlibs
- beos backend
- ------------
- No dependencies in itself other than an installed BeOS system, but cairo
- requires a font backend. See the freetype dependency list.
+ xlib-xrender backend
+ --------------------
+ Xrender >= 0.6 http://freedesktop.org/Software/xlibs
- os2 backend
- -----------
- Cairo should run on any recent version of OS/2 or eComStation, but it
- requires a font backend. See the freetype dependency list. Ready to use
- packages and developer dependencies are available at Netlabs:
- ftp://ftp.netlabs.org/pub/cairo
+ quartz backend
+ --------------
+ MacOS X >= 10.4 with Xcode >= 2.4
-Font backends:
+ win32 backend
+ -------------
+ Microsoft Windows 2000 or newer[*].
+Font backends (required to have at least one)
+---------------------------------------------
freetype font backend
---------------------
- freetype >= 2.1.4 http://freetype.org
+ freetype >= 2.1.9 http://freetype.org
fontconfig http://fontconfig.org
- win32 font backend
- ------------------
- [*]
+ quartz-font backend
+ -------------------
+ MacOS X >= 10.4 with Xcode >= 2.4
- atsui font backend
+ win32 font backend
------------------
- [*]
-
- [*] I don't know specifically what packages might need to be
- installed on a Mac OS X system to use the Quartz and ATSUI
- backends. As far as win32, the situation is rather complex:
+ Microsoft Windows 2000 or newer[*].
- The Win32 backend should work on Windows 2000 and newer
+ [*] The Win32 backend should work on Windows 2000 and newer
(excluding Windows Me.) Most testing has been done on
Windows XP. While some portions of the code have been
adapted to work on older versions of Windows, considerable
- work still needs to be done to get cairo running in these
+ work still needs to be done to get cairo running in those
environments.
- Cairo can be compiled on Windows either with the GCC
+ Cairo can be compiled on Windows with either the gcc
toolchain (see http://www.mingw.org) or with Microsoft
- Visual C++. Makefiles or project files for compiling with
- MSVC are however not provided as of this release. We have
- received reports that MSVC 6.0 compiles parts of cairo
- incorrectly, (leading to incorrect color). MSVC 7.0 is
- known to work.
+ Visual C++. If the gcc toolchain is used, the standard
+ build instructions using configure apply, (see INSTALL).
+ If Visual C++ is desired, GNU make is required and
+ Makefile.win32 can be used via 'make -f Makefile.win32'.
+ The compiler, include paths, and library paths must be set
+ up correctly in the environment.
+
+ MSVC versions earlier than 7.1 are known to miscompile
+ parts of cairo and pixman, and so should be avoided. MSVC
+ 7.1 or later, including the free Microsoft Visual Studio
+ Express editions, produce correct code.
+
+Experimental surface backends
+-----------------------------
+ glitz
+ -------------
+ glitz >= 0.4.4 http://freedesktop.org/Software/glitz
+
+ xcb backend
+ -----------
+ XCB http://xcb.freedesktop.org
+
+ beos backend
+ ------------
+ No dependencies in itself other than an installed BeOS system, but cairo
+ requires a font backend. See the freetype dependency list.
+
+ os2 backend
+ -----------
+ Cairo should run on any recent version of OS/2 or eComStation, but it
+ requires a font backend. See the freetype dependency list. Ready to use
+ packages and developer dependencies are available at Netlabs:
+ ftp://ftp.netlabs.org/pub/cairo
Compiling
=========
commit c642a401959c183de2afa3fba2c4206aa0fdbc0c
Author: Carl Worth <cworth at cworth.org>
Date: Sun Apr 6 01:13:17 2008 -0700
Revert "[README] Remove the Dependencies section as it falls out of date easily"
This reverts commit 5f38e215ed4ec930492ee373db37a767d85a6ee8.
It's true that the dependencies can fall out of date, but it's really
unkind to not provide users with this information. I think we can
compromise by committing to update this information before major
releases.
diff --git a/README b/README
index cdd30dd..76b2c2b 100644
--- a/README
+++ b/README
@@ -55,6 +55,95 @@ Roadmap and unscheduled things to do, (please feel free to help out):
http://cairographics.org/roadmap
http://cairographics.org/todo
+Dependencies
+============
+The set of libraries needed to compile cairo depends on which backends
+are enabled when cairo is configured. Here are the dependencies for
+each backend:
+
+Surface backends:
+
+ image backend (required)
+ ------------------------
+ pixman http://cairographics.org/releases
+ or: git://git.cairographics.org/git/pixman
+
+ glitz backend
+ -------------
+ glitz >= 0.4.4 http://freedesktop.org/Software/glitz
+
+ pdf backend
+ -----------
+ freetype >= 2.1.4 http://freetype.org
+ zlib http://www.gzip.org/zlib
+
+ postscript backend
+ ------------------
+ freetype >= 2.1.4 http://freetype.org
+ zlib http://www.gzip.org/zlib
+
+ quartz backend
+ --------------
+ [*]
+
+ win32 backend
+ -------------
+ [*]
+
+ xcb backend
+ -----------
+ XCB http://xcb.freedesktop.org
+
+ xlib backend
+ ------------
+ Xrender >= 0.6 http://freedesktop.org/Software/xlibs
+
+ beos backend
+ ------------
+ No dependencies in itself other than an installed BeOS system, but cairo
+ requires a font backend. See the freetype dependency list.
+
+ os2 backend
+ -----------
+ Cairo should run on any recent version of OS/2 or eComStation, but it
+ requires a font backend. See the freetype dependency list. Ready to use
+ packages and developer dependencies are available at Netlabs:
+ ftp://ftp.netlabs.org/pub/cairo
+
+Font backends:
+
+ freetype font backend
+ ---------------------
+ freetype >= 2.1.4 http://freetype.org
+ fontconfig http://fontconfig.org
+
+ win32 font backend
+ ------------------
+ [*]
+
+ atsui font backend
+ ------------------
+ [*]
+
+ [*] I don't know specifically what packages might need to be
+ installed on a Mac OS X system to use the Quartz and ATSUI
+ backends. As far as win32, the situation is rather complex:
+
+ The Win32 backend should work on Windows 2000 and newer
+ (excluding Windows Me.) Most testing has been done on
+ Windows XP. While some portions of the code have been
+ adapted to work on older versions of Windows, considerable
+ work still needs to be done to get cairo running in these
+ environments.
+
+ Cairo can be compiled on Windows either with the GCC
+ toolchain (see http://www.mingw.org) or with Microsoft
+ Visual C++. Makefiles or project files for compiling with
+ MSVC are however not provided as of this release. We have
+ received reports that MSVC 6.0 compiles parts of cairo
+ incorrectly, (leading to incorrect color). MSVC 7.0 is
+ known to work.
+
Compiling
=========
See the INSTALL document for build instructions.
commit b61d1b01e94b3d8daa288b8d5d183f093d989582
Author: Carl Worth <cworth at cworth.org>
Date: Sun Apr 6 01:07:32 2008 -0700
Change default filter from BEST to GOOD
Right now the two filters are implemented identically, so there's
no real change for now. But in the future, it's conceivable that an
X server could implement some crazy, high-quality filter for BEST
without regard to performance, (since that's what BEST means).
Meanwhile, GOOD actually captures what we want by default which is
a good mix of both quality and performance.
diff --git a/src/cairoint.h b/src/cairoint.h
index 01ad567..0389c26 100644
--- a/src/cairoint.h
+++ b/src/cairoint.h
@@ -761,7 +761,7 @@ struct _cairo_color {
#define CAIRO_EXTEND_SURFACE_DEFAULT CAIRO_EXTEND_NONE
#define CAIRO_EXTEND_GRADIENT_DEFAULT CAIRO_EXTEND_PAD
-#define CAIRO_FILTER_DEFAULT CAIRO_FILTER_BEST
+#define CAIRO_FILTER_DEFAULT CAIRO_FILTER_GOOD
struct _cairo_pattern {
cairo_pattern_type_t type;
More information about the cairo-commit
mailing list