[cairo] Problems with cairo_get_line_width and "new" semantics
Carl Worth
cworth at cworth.org
Fri May 19 17:30:58 PDT 2006
On Tue, 16 May 2006 18:35:03 -0400 (EDT), Behdad Esfahbod wrote:
> On Tue, 16 May 2006, Bill Spitzak wrote:
>
> > Better proposal for dashes to make pens only be a matrix:
> >
> > The gstate has a "pen space" where the pen is a 1-unit diameter circle
[...]
> I prefer cairo_[gs]et_pen_matrix instead. That is more
> consistent with font_matrix functions, and is more extensible.
> (say we may want to add cairo_set_pen_path in the future...)
Does this look like what we want? This is documentation I just wrote
up for cairo_set_line_width and cairo_set_pen_matrix. I'll follow up
shortly with cairo_get_line_width and cairo_get_pen_matrix along with
implementations (which should be only minor tweaks to my current
line-width-scale branch I think).
-Carl
/**
* cairo_set_line_width:
* @cr: a #cairo_t
* @width: a line width, as a user-space value
*
* Sets the pen matrix so that the pen is a circle with diameter
* @width in user-space. The pen is used by the various stroking
* operations, (see cairo_stroke() and related functions).
*
* Although the pen is circular in user space, the device-space pen
* may be an ellipse due to scaling/shear/rotation of the CTM). This
* can be useful for achieving non-uniform scaling of the stroke width
* in various directions.
*
* Note: The pen is "locked" to the user space in effect at the time
* of cairo_set_pen_matrix. This means that further modifications of
* the current transformation matrix will not affect the pen.
*
* As with the other stroke parameters, the pen is examined by
* cairo_stroke(), cairo_stroke_extents(), and cairo_stroke_to_path(),
* but does not have any effect during path construction.
*
* See also cairo_set_pen() for a way to specify the pen matrix
* directly. (cairo_set_line_width is equivalent to calling
* cairo_set_pen_matrix with a matrix of [@line_width 0 0 @line_width
* 0 0]).
**/
void
cairo_set_line_width (cairo_t *cr, double width)
/**
* cairo_set_pen_matrix:
* @cr: a #cairo_t
* @matrix: a matrix mapping from pen space to user space
*
* Sets the pen matrix (mapping from pen space to user space) within
* the cairo context. The pen is used by the various stroking
* operations, (see cairo_stroke() and related functions).
*
* Pen space is a coordinate space in which the pen exists as a circle
* with a diameter of 1 unit. The pen matrix maps from this space to
* user space, providing for elliptical pens of any size/orientation.
*
* Note: The pen matrix is "locked" to the user space in effect at the
* time of cairo_set_pen_matrix. This means that further modifications
* of the current transformation matrix will not affect the pen.
*
* As with the other stroke parameters, the pen is examined by
* cairo_stroke(), cairo_stroke_extents(), and cairo_stroke_to_path(),
* but does not have any effect during path construction.
*
* Caution: It is an error to pass a singular matrix to this
* function. If you are unsure if the matrix is invertible and want to
* avoid causing a non-recoverable error to be set in the cairo
* context, then you may want to test the matrix first by checking the
* return value of cairo_matrix_invert() on a copy of the matrix.
*
* See also cairo_set_line_width() for a more convenient way to
* specify the pen, (by using a single scale factor rather than an
* explicit matrix).
**/
void
cairo_set_pen_matrix (cairo_t *cr,
const cairo_matrix_t *matrix)
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/cairo/attachments/20060519/98241cc3/attachment.pgp
More information about the cairo
mailing list