Module: Prawn::Graphics::Patterns

Defined in:
lib/prawn/shadings.rb

Overview

This module implements Shading patterns.

Both fill_gradient and stroke_gradient accept absolutely identical sets of arguments. The only difference, obviously, is that one sets fill shading and the other sets stroke shading.

Basic gradients

Linear and radial gradients are one of the simplest shadings supported by PDF.

Linear gradient

fill_gradient(from, to, color1, color2)
from

This is the starting point of the gradient. It must be an arrays of two values: [x, y].

to

This is the ending point of the gradient. Format is the same: [x, y].

color1

Color of the gradient at the starting point.

color2

Color of the gradient at the ending point of the gradient.

Please note that both colors must be in the same color space.

Radial gradient

fill_gradient(from, r1, to, r2, color1, color2)
from

This is the starting point of the gradient. It must be an arrays of two values: [x, y].

r1

Radius of the starting circle.

to

This is the ending point of the gradient. Format is the same: [x, y].

r2

Radius of the ending circle.

color1

Color of the gradient at the starting point.

color2

Color of the gradient at the ending point of the gradient.

Please note that both colors must be in the same color space.

More complex gradients

PDF is capable of creating very complex shadings. Though, this functionality is rarely used.

Because this gradients require variable amounts of data to be properly constructed gradient methods are called with a single parameter stating the type of gradient you want to produce and a block that returns actual data for gradient.

Note

This types of shading are not supported by all renderers. For example PDF.js doesn’t support any of this shadings. OS X Preview (10.8) has problems with flags other than 0 and renders Tensor-Product Patch Meshes exactly the same as Coons Patch Meshes.

Free-Form Gouraud-Shaded Triangle Meshes

fill_gradient(:ffgstm) {
  [
    # vertices
  ]
}

The data is an Array of vertices. Each vertex has the following format: [flag, x, y, color].

Colors of all vertices must be in the same color space.

Please refer to PDF Refernce, Section 4.6.3, Shading Types, Type 4 Shadings for more details on the meaning of the vertex fields.

Lattice-Form Gouraud-Shaded Triangle Meshes

fill_gradient(:lfgstm) {
  [
    # data
  ]
}

The data is a rectangular matrix of vertices. That is an array of rows (arrays) of vertices. It must have at least 2 rows and at least 2 column. Each vertex has the following format: [x, y, color].

Colors of all vertices must be in the same color space.

Please refer to PDF Refernce, Section 4.6.3, Shading Types, Type 5 Shadings for more details on the meaning of the vertex fields.

Coons Patch Meshes

fill_gradient(:cpm) {
  [
    # data
  ]
}

The data is an array of patches. There are two types of patches. They’re distinguished by their flag parameter.

First one is a stand alone patches. Their flag = 0. They have a form of [0 (flag), x1, y1, x2, y2, x3, y3, x4, y4, x5, y5, x6, y6, x7, y7, x8, y8, x9, y9, x10, y10, x11, y11, x12, y12, c1, c2, c3, c4].

The second is a edge-sharing patches. Their flag is either 1, 2, or 3. And they have 4 less points (because they borrow them from previous patch) and 2 less colors. They have a form of [flag, x5, y5, x6, y6, x7, y7, x8, y8, x9, y9, x10, y10, x11, y11, x12, y12, c3, c4].

Please refer to PDF Refernce, Section 4.6.3, Shading Types, Type 6 Shadings for more details on the meaning of the patch fields.

Tensor-Product Patch Meshes

fill_gradient(:tppm) {
  [
    # data
  ]
}

This type of shading is very similar to Coons Patch Mesh except it has 4 extra pairs of coordinates in every patch, right before the colors.

Please refer to PDF Refernce, Section 4.6.3, Shading Types, Type 7 Shadings for more details on the meaning of the patch fields.

Instance Method Summary collapse

Instance Method Details

#fill_gradient(*args, &block) ⇒ Object

:call-seq:

fill_gradient(from, to, color1, color2)
fill_gradient(from, r1, to, r2, color1, color2)
fill_gradient(complex_shading_type) { }

Sets the fill gradient.



164
165
166
167
168
169
170
171
172
 
# File 'lib/prawn/shadings.rb', line 164

def fill_gradient(*args, &block)
  if args[1].is_a?(Array) || args[2].is_a?(Array) || args[0].is_a?(Symbol)
    set_gradient(:fill, *args, &block)
  else
    warn "[DEPRECATION] 'fill_gradient(point, width, height,...)' is deprecated in favor of 'fill_gradient(from, to,...)'. " +
         "Old arguments will be removed in release 1.1"
    set_gradient :fill, args[0], [args[0].first, args[0].last - args[2]], args[3], args[4]
  end
end

#stroke_gradient(*args, &block) ⇒ Object

:call-seq:

stroke_gradient(from, to, color1, color2)
stroke_gradient(from, r1, to, r2, color1, color2)
stroke_gradient(complex_shading_type) { }

Sets the stroke gradient.



181
182
183
184
185
186
187
188
189
 
# File 'lib/prawn/shadings.rb', line 181

def stroke_gradient(*args, &block)
  if args[1].is_a?(Array) || args[2].is_a?(Array) ||  args[0].is_a?(Symbol)
    set_gradient(:stroke, *args, &block)
  else
    warn "[DEPRECATION] 'stroke_gradient(point, width, height,...)' is deprecated in favor of 'stroke_gradient(from, to,...)'. " +
         "Old arguments will be removed in release 1.1"
    set_gradient :stroke, args[0], [args[0].first, args[0].last - args[2]], args[3], args[4]
  end
end