diff options
Diffstat (limited to 'doc/reference/patterns.rst')
| -rw-r--r-- | doc/reference/patterns.rst | 286 |
1 files changed, 286 insertions, 0 deletions
diff --git a/doc/reference/patterns.rst b/doc/reference/patterns.rst new file mode 100644 index 0000000..9fab1d2 --- /dev/null +++ b/doc/reference/patterns.rst @@ -0,0 +1,286 @@ +.. _patterns: + +******** +Patterns +******** + +.. currentmodule:: cairo + + +Patterns are the paint with which cairo draws. The primary use of patterns is +as the source for all cairo drawing operations, although they can also be used +as masks, that is, as the brush too. + +A cairo *Pattern* is created by using one of the *PatternType* constructors +listed below, or implicitly through *Context.set_source_<type>()* methods. + + +class Pattern() +=============== + +*Pattern* is the abstract base class from which all the other pattern classes +derive. It cannot be instantiated directly. + +.. class:: Pattern() + + .. method:: get_extend() + + :returns: the current extend strategy used for drawing the *Pattern*. + :rtype: int + + Gets the current extend mode for the *Pattern*. See + :ref:`EXTEND attributes <constants_EXTEND>` + for details on the semantics of each extend strategy. + + .. method:: get_matrix() + + :returns: a new :class:`Matrix` which stores a copy of the *Pattern's* transformation matrix + + .. method:: set_extend(extend) + + :param extend: an :ref:`EXTEND <constants_EXTEND>` describing how the + area outside of the *Pattern* will be drawn + + Sets the mode to be used for drawing outside the area of a *Pattern*. + + The default extend mode is :data:`cairo.EXTEND_NONE` for + :class:`SurfacePattern` and :data:`cairo.EXTEND_PAD` for + :class:`Gradient` Patterns. + + .. method:: set_matrix(matrix) + + :param matrix: a :class:`Matrix` + + Sets the *Pattern's* transformation matrix to *matrix*. This matrix is a + transformation from user space to pattern space. + + When a *Pattern* is first created it always has the identity matrix for + its transformation matrix, which means that pattern space is initially + identical to user space. + + Important: Please note that the direction of this transformation matrix + is from user space to pattern space. This means that if you imagine the + flow from a *Pattern* to user space (and on to device space), then + coordinates in that flow will be transformed by the inverse of the + *Pattern* matrix. + + For example, if you want to make a *Pattern* appear twice as large as it + does by default the correct code to use is:: + + matrix = cairo.Matrix(xx=0.5,yy=0.5) + pattern.set_matrix(matrix) + + Meanwhile, using values of 2.0 rather than 0.5 in the code above would + cause the *Pattern* to appear at half of its default size. + + Also, please note the discussion of the user-space locking semantics of + :class:`Context.set_source`. + + +class SolidPattern(:class:`Pattern`) +==================================== + +.. class:: SolidPattern(red, green, blue, alpha=1.0) + + :param red: red component of the color + :type red: float + :param green: green component of the color + :type green: float + :param blue: blue component of the color + :type blue: float + :param alpha: alpha component of the color + :type alpha: float + :returns: a new *SolidPattern* + :raises: *MemoryError* in case of no memory + + Creates a new *SolidPattern* corresponding to a translucent color. The + color components are floating point numbers in the range 0 to 1. If the + values passed in are outside that range, they will be clamped. + + + .. method:: get_rgba() + + :returns: (red, green, blue, alpha) a tuple of float + + Gets the solid color for a *SolidPattern*. + + .. versionadded:: 1.4 + + +class SurfacePattern(:class:`Pattern`) +====================================== + +.. class:: SurfacePattern(surface) + + :param surface: a cairo :class:`Surface` + :returns: a newly created *SurfacePattern* for the given surface. + :raises: *MemoryError* in case of no memory. + + .. method:: get_filter() + + :returns: the current :ref:`FILTER <constants_filter>` used for + resizing the *SurfacePattern*. + + .. method:: get_surface() + + :returns: the :class:`Surface` of the *SurfacePattern*. + + .. versionadded:: 1.4 + + .. method:: set_filter(filter) + + :param filter: a :ref:`FILTER <constants_filter>` describing the filter + to use for resizing the *Pattern* + + Note that you might want to control filtering even when you do not have + an explicit *Pattern* object, (for example when using + :meth:`Context.set_source_surface`). In these cases, it is convenient to use + :meth:`Context.get_source` to get access to the pattern that cairo creates + implicitly. For example:: + + context.set_source_surface(image, x, y) + surfacepattern.set_filter(context.get_source(), cairo.FILTER_NEAREST) + + +class Gradient(:class:`Pattern`) +================================ + +*Gradient* is an abstract base class from which other *Pattern* classes +derive. It cannot be instantiated directly. + +.. class:: Gradient() + + .. method:: add_color_stop_rgb(offset, red, green, blue) + + :param offset: an offset in the range [0.0 .. 1.0] + :type offset: float + :param red: red component of color + :type red: float + :param green: green component of color + :type green: float + :param blue: blue component of color + :type blue: float + + Adds an opaque color stop to a *Gradient* pattern. The offset specifies + the location along the gradient's control vector. For example, a + *LinearGradient's* control vector is from (x0,y0) to (x1,y1) while a + *RadialGradient's* control vector is from any point on the start circle + to the corresponding point on the end circle. + + The color is specified in the same way as in :meth:`Context.set_source_rgb`. + + If two (or more) stops are specified with identical offset values, they + will be sorted according to the order in which the stops are added, + (stops added earlier will compare less than stops added later). This can + be useful for reliably making sharp color transitions instead of the + typical blend. + + .. method:: add_color_stop_rgba(offset, red, green, blue, alpha) + + :param offset: an offset in the range [0.0 .. 1.0] + :type offset: float + :param red: red component of color + :type red: float + :param green: green component of color + :type green: float + :param blue: blue component of color + :type blue: float + :param alpha: alpha component of color + :type alpha: float + + Adds an opaque color stop to a *Gradient* pattern. The offset specifies + the location along the gradient's control vector. For example, a + *LinearGradient's* control vector is from (x0,y0) to (x1,y1) while a + *RadialGradient's* control vector is from any point on the start circle + to the corresponding point on the end circle. + + The color is specified in the same way as in :meth:`Context.set_source_rgb`. + + If two (or more) stops are specified with identical offset values, they + will be sorted according to the order in which the stops are added, + (stops added earlier will compare less than stops added later). This can + be useful for reliably making sharp color transitions instead of the + typical blend. + + +class LinearGradient(:class:`Gradient`) +======================================= +.. class:: LinearGradient(x0, y0, x1, y1) + + :param x0: x coordinate of the start point + :type x0: float + :param y0: y coordinate of the start point + :type y0: float + :param x1: x coordinate of the end point + :type x1: float + :param y1: y coordinate of the end point + :type y1: float + :returns: a new *LinearGradient* + :raises: *MemoryError* in case of no memory + + Create a new *LinearGradient* along the line defined by (x0, y0) and (x1, + y1). Before using the *Gradient* pattern, a number of color stops should + be defined using :meth:`Gradient.add_color_stop_rgb` or + :meth:`Gradient.add_color_stop_rgba` + + Note: The coordinates here are in pattern space. For a new *Pattern*, + pattern space is identical to user space, but the relationship between the + spaces can be changed with :meth:`Pattern.set_matrix` + + .. method:: get_linear_points() + + :returns: (x0, y0, x1, y1) - a tuple of float + + * x0: return value for the x coordinate of the first point + * y0: return value for the y coordinate of the first point + * x1: return value for the x coordinate of the second point + * y1: return value for the y coordinate of the second point + + Gets the gradient endpoints for a *LinearGradient*. + + .. versionadded:: 1.4 + + +class RadialGradient(:class:`Gradient`) +======================================= +.. class:: RadialGradient(cx0, cy0, radius0, cx1, cy1, radius1) + + :param cx0: x coordinate for the center of the start circle + :type cx0: float + :param cy0: y coordinate for the center of the start circle + :type cy0: float + :param radius0: radius of the start circle + :type radius0: float + :param cx1: x coordinate for the center of the end circle + :type cx1: float + :param cy1: y coordinate for the center of the end circle + :type cy1: float + :param radius1: radius of the end circle + :type radius1: float + :returns: the newly created *RadialGradient* + :raises: *MemoryError* in case of no memory + + Creates a new *RadialGradient* pattern between the two circles defined by + (cx0, cy0, radius0) and (cx1, cy1, radius1). Before using the gradient + pattern, a number of color stops should be defined using + :meth:`Gradient.add_color_stop_rgb` or :meth:`Gradient.add_color_stop_rgba`. + + Note: The coordinates here are in pattern space. For a new pattern, pattern + space is identical to user space, but the relationship between the spaces + can be changed with :meth:`Pattern.set_matrix`. + + .. method:: get_radial_circles() + + :returns: (x0, y0, r0, x1, y1, r1) - a tuple of float + + * x0: return value for the x coordinate of the center of the first circle + * y0: return value for the y coordinate of the center of the first circle + * r0: return value for the radius of the first circle + * x1: return value for the x coordinate of the center of the second circle + * y1: return value for the y coordinate of the center of the second circle + * r1: return value for the radius of the second circle + + Gets the *Gradient* endpoint circles for a *RadialGradient*, each + specified as a center coordinate and a radius. + + .. versionadded:: 1.4 |