The class represents a Cairo surface pattern (or surface pattern or, in the narrower sense of Cairo, a surface brush) as returned by Cairo.SolidPattern or Cairo.LinearGradient.

Example Cairo.LinearGradient:

Public Sub CairoScriptLinearGradient()
 
  Dim aColors0 As Integer[] = [Color.Blue, Color.Yellow, Color.Red, Color.Gray, Color.Green, Color.Orange]
  Dim aColors As Float[][]
  Dim fPosition As Float 
 
  aColors = BuildColorStops(aColors0, Null)
 
  GenerateNewImage()
  SetImageBorder()  
 
  Cairo.Begin(hImage) 
    Cairo.Translate(xTranslate, yTranslate)
    Cairo.Scale(xScale, yScale)
    DrawCoordinateSystem() ' +y ▲
 
    Cairo.MoveTo(50, 40)
    Cairo.Source = Cairo.LinearGradient(50, 40, 450, 200, aColors)
    Cairo.Rectangle(50, 40, 450, 200)
    Cairo.Fill()
  Cairo.End()
 
End

Figure 25.1.5.1: Colour gradient of six colours as a surface pattern

The CairoPattern class has only two properties:

• CairoPattern.Filter
• CairoPattern.Matrix

Sets or returns the filter that is used when enlarging under this pattern. A “filter” is to be understood here as an algorithm that calculates a magnification. When selecting the algorithm, these two conflicting interests must be weighed up: required computing time and quality. The filter property can have one of the following values

• Cairo.FilterFast
• Cairo.FilterGood
• Cairo.FilterBest
• Cairo.FilterNearest
• Cairo.FilterBilinear
• Cairo.FilterGaussian (currently not implemented → 19.02.2024)

If you want to control the filter without explicitly creating a CairoPattern object, use Cairo.Source to get access to the current pattern:

Cairo.Source.Filter = Cairo.FilterNearest

Sets or returns the pattern transformation matrix. This matrix transforms user space into pattern space. If a pattern object is created, this matrix is the identity, i.e. the pattern space is equal to the user space.

Note that the direction of the transformation is from user space to pattern space. This means - if you imagine the transformation of a pattern from pattern space via user space to device space - that the first step from pattern space to user space is described by the inverse (!) of the Cairo pattern matrix. For example, if you want to make a pattern twice as large as it normally is, use :

Dim MyPattern As CairoPattern = ... 
MyPattern.Matrix = CairoMatrix().Scale(0.5, 0.5) 

If you were to use the values 2.0 instead of 0.5, the pattern would only be half the size instead of twice the size due to the inverse CairoPattern matrix!