mirror of
https://gitlab.freedesktop.org/cairo/cairo.git
synced 2026-01-20 03:10:35 +01:00
read-only mirror of https://gitlab.freedesktop.org/cairo/cairo
31f5aafa36
Seems like all over the code, we have been using negated device_offset
values for glyph surfaces. Here is all the math(!):
A device_transform converts from device space (a conceptual space) to
surface space. For simple cases of translation only, it's called a
device_offset and is public API (cairo_surface_[gs]et_device_offset).
A possibly better name for those functions could have been
cairo_surface_[gs]et_origing. So, that's what they do: they set where
the device-space origin (0,0) is in the surface. If the origin is inside
the surface, device_offset values are positive. It may look like this:
Device space:
(-x,-y) <-- negative numbers
+----------------+
| . |
| . |
|......(0,0) <---|-- device-space origin
| |
| |
+----------------+
(width-x,height-y)
Surface space:
(0,0) <-- surface-space origin
+---------------+
| . |
| . |
|......(x,y) <--|-- device_offset
| |
| |
+---------------+
(width,height)
In other words: device_offset is the coordinates of the device-space
origin relative to the top-left of the surface.
We use device offsets in a couple of places:
- Public API: To let toolkits like Gtk+ give user a surface that
only represents part of the final destination (say, the expose
area), but has the same device space as the destination. In these
cases device_offset is typically negative. Example:
application window
+---------------+
| . |
| (x,y). |
|......+---+ |
| | | <--|-- expose area
| +---+ |
+---------------+
In this case, the user of cairo API can set the device_space on
the expose area to (-x,-y) to move the device space origin to that
of the application window, such that drawing in the expose area
surface and painting it in the application window has the same
effect as drawing in the application window directly. Gtk+ has
been using this feature.
- Glyph surfaces: In most font rendering systems, glyph surfaces
have an origin at (0,0) and a bounding box that is typically
represented as (x_bearing,y_bearing,width,height). Depending on
which way y progresses in the system, y_bearing may typically be
negative (for systems similar to cairo, with origin at top left),
or be positive (in systems like PDF with origin at bottom left).
No matter which is the case, it is important to note that
(x_bearing,y_bearing) is the coordinates of top-left of the glyph
relative to the glyph origin. That is, for example:
Scaled-glyph space:
(x_bearing,y_bearing) <-- negative numbers
+----------------+
| . |
| . |
|......(0,0) <---|-- glyph origin
| |
| |
+----------------+
(width+x_bearing,height+y_bearing)
Note the similarity of the origin to the device space. That is
exactly how we use the device_offset to represent scaled glyphs:
to use the device-space origin as the glyph origin.
Now compare the scaled-glyph space to device-space and surface-space
and convince yourself that:
(x_bearing,y_bearing) = (-x,-y) = - device_offset
That's right. If you are not convinced yet, contrast the definition
of the two:
"(x_bearing,y_bearing) is the coordinates of top-left of the
glyph relative to the glyph origin."
"In other words: device_offset is the coordinates of the
device-space origin relative to the top-left of the surface."
and note that glyph origin = device-space origin.
So, that was the bug. Fixing it removed lots of wonders and magic
negation signs.
The way I discovered the bug was that in the user-font API, to make
rendering the glyph from meta-surface to an image-surface work I had
to do:
cairo_surface_set_device_offset (surface, -x_bearing, -y_bearing);
_cairo_meta_surface_replay (meta_surface, surface);
cairo_surface_set_device_offset (surface, x_bearing, y_bearing);
This suggested that the use of device_offset for glyph origin is
different from its use for rendering with meta-surface. This reminded
me of the large comment in the xlib backend blaming XRender for having
weird glyph space, and of a similar problem I had in the PS backend
for bitmap glyph positioning (see
|
||
|---|---|---|
| boilerplate | ||
| doc | ||
| perf | ||
| src | ||
| test | ||
| util | ||
| .gitignore | ||
| acinclude.m4 | ||
| AUTHORS | ||
| autogen.sh | ||
| BIBLIOGRAPHY | ||
| BUGS | ||
| ChangeLog.mk | ||
| CODING_STYLE | ||
| configure.in | ||
| COPYING | ||
| COPYING-LGPL-2.1 | ||
| COPYING-MPL-1.1 | ||
| gtk-doc.make | ||
| INSTALL | ||
| Makefile.am | ||
| Makefile.win32 | ||
| NEWS | ||
| PORTING_GUIDE | ||
| README | ||
| RELEASING | ||
| ROADMAP | ||
| TODO | ||
Cairo - Multi-platform 2D graphics library http://cairographics.org What is cairo ============= Cairo is a 2D graphics library with support for multiple output devices. Currently supported output targets include the X Window System, win32, and image buffers, as well as PDF, PostScript, and SVG file output. Experimental backends include OpenGL (through glitz), Quartz, XCB, BeOS, OS/2, and DirectFB. Cairo is designed to produce consistent output on all output media while taking advantage of display hardware acceleration when available (for example, through the X Render Extension). The cairo API provides operations similar to the drawing operators of PostScript and PDF. Operations in cairo include stroking and filling cubic Bézier splines, transforming and compositing translucent images, and antialiased text rendering. All drawing operations can be transformed by any affine transformation (scale, rotation, shear, etc.). Cairo has been designed to let you draw anything you want in a modern 2D graphical user interface. At the same time, the cairo API has been designed to be as fun and easy to learn as possible. If you're not having fun while programming with cairo, then we have failed somewhere---let us know and we'll try to fix it next time around. Cairo is free software and is available to be redistributed and/or modified under the terms of either the GNU Lesser General Public License (LGPL) version 2.1 or the Mozilla Public License (MPL) version 1.1. Where to get more information about cairo ========================================= The primary source of information about cairo is: http://cairographics.org/ The latest releases of cairo can be found at: http://cairographics.org/releases Snapshots of in-development versions of cairo: http://cairographics.org/snapshots The programming manual for using cairo: http://cairographics.org/manual Mailing lists for contacting cairo users and developers: http://cairographics.org/lists Answers to some frequently asked questions about cairo: http://cairographics.org/FAQ 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 ------------- pixman git://git.freedesktop.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. History ======= Cairo was originally developed by Carl Worth <cworth@cworth.org> and Keith Packard <keithp@keithp.com>. Many thanks are due to Lyle Ramshaw without whose patient help our ignorance would be much more apparent. Since the original development, many more people have contributed to cairo. See the AUTHORS files for as complete a list as we've been able to compile so far.