[cairo] Problems with cairo_get_line_width and "new" semantics

[Carl Worth]

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