What I've learned about gradients (keywords: blend, shading, pattern)

#!/usr/bin/perl

# Blended fill

use strict;
use warnings;


use PDF::API2;
use PDF::API2::Basic::PDF::Utils;

use constant mm => 25.4 / 72;
use constant in => 1 / 72;
use constant pt => 1;

my $pdf = PDF::API2->new();

my $page = $pdf->page;
$page->mediabox('A4');

my $gfx=$page->gfx;

my $shade = linear_gradient(
	$pdf,
	[ 0.0000 => 1, 0, 0 ], # At zero, it's red
	[ 0.7500 => 0, 1, 0 ], # At 75%, it's green
	[ 1.0000 => 0, 0, 1 ], # At 100% it's blue
);


$gfx->strokecolor( (0.65) x 3 );
$gfx->linewidth(1);
$gfx->fillcolor( gradient_shape($pdf, $shade, 10/mm, 10/mm, 190/mm, 277/mm) );
$gfx->rect( 10/mm, 10/mm, 190/mm, 277/mm );
$gfx->fillstroke;



$pdf->saveas("$0.pdf");



# Arguments for gradient_shape are:
# * The PDF Object
# * The Shading Object (from linear_gradient below)
# * The X, Y, W and H of the shape (in relation to the page) to fill with the shading
#   If you're filling a rect(), use the same values here as for the rect()
sub gradient_shape{
	my $pdf = shift;
	my $sh = shift;
	my ($x, $y, $w, $h) = @_;

	my $pt=$pdf->pattern();
	$pt->{Type}=PDFName('Pattern');
	$pt->{PatternType}=PDFNum(2); # 2 = Shading
	# See section 4.2 of the spec for discussion of the matrix:
	$pt->{Matrix}=PDFArray(PDFNum($w),PDFNum(0),PDFNum(0),PDFNum($h),PDFNum($x),PDFNum($y));
	$pt->{Shading}=$sh;

	return $pt

}



# This function creates the shading object you'll need for 'gradient_shape'

# Arguments for linear_gradient are:
# * The PDF Object
# * A list of points to blend between
#   * Each point is an array ref comprised of the point (between 0 and 1) that the point represents
#   * Followed by three values (for R, G, B).
#   Example: [ 0 => 1, 0, 0 ] means that at the zero point, make it red.
#   You need at least two points to blend between.

sub linear_gradient{
	my( $pdf, @points ) = @_;

	# Sort the points by their position
	@points = sort { $a->[0] <=> $b->[0] } @points;

	my $sh = $pdf->shading;

	$sh->{ShadingType}=PDFNum(2); # 2 = Linear, 3 = Radial
	$sh->{ColorSpace}=PDFName('DeviceRGB');

	# If you want to mess with the angle, here's where you do it.
	# This runs up the Y axis between the first and last point.
	$sh->{Coords}=PDFArray(
		PDFNum(0),PDFNum( $points[0][0] ),  # X1, Y1
		PDFNum(0),PDFNum( $points[$#points][0]) # X2, Y2
	);

	# If there's just two points, then use the exponential extrapolation function
	if( @points == 2 ){

		$sh->{Function} = PDFDict();
		$sh->{Function}->{FunctionType}=PDFNum(2);
		$sh->{Function}->{Domain}=PDFArray(PDFNum(0),PDFNum(1));
		$sh->{Function}->{C0}=PDFArray(PDFNum($points[0][1]),PDFNum($points[0][2]),PDFNum($points[0][3]));
		$sh->{Function}->{C1}=PDFArray(PDFNum($points[1][1]),PDFNum($points[1][2]),PDFNum($points[1][3]));
		$sh->{Function}->{N}=PDFNum(1);

	}
	# If there's more than two points, we need to stitch
	else {
		# Make a part to blend between each of the points. It's an exponential extrapolation function as above.
		my @part = ();
		for my $p ( 0 .. $#points - 1 ){
			$part[$p] = PDFDict();
			$part[$p]->{FunctionType}=PDFNum(2);
			$part[$p]->{Domain}=PDFArray(PDFNum(0),PDFNum(1));
			$part[$p]->{C0}=PDFArray(PDFNum($points[$p][1]),PDFNum($points[$p][2]),PDFNum($points[$p][3]));
			$part[$p]->{C1}=PDFArray(PDFNum($points[$p+1][1]),PDFNum($points[$p+1][2]),PDFNum($points[$p+1][3]));
			$part[$p]->{N}=PDFNum(1);
		}

		# Now stitch them all together
		$sh->{Function}=PDFDict();
		$sh->{Function}->{FunctionType} = PDFNum(3); # 3 = Stitching
		$sh->{Function}->{Functions} = PDFArray( @part );
		# Set the bounds (the points at which each part starts/stops) according to the input points.
		$sh->{Function}->{Bounds} = PDFArray( map { PDFNum( $_->[0] ) } @points[1 .. $#points-1] );
		# Each part goes from 0 to 1
		$sh->{Function}->{Encode} = PDFArray( ( PDFNum( 0 ), PDFNum( 1 ) ) x @part );
		# As does the whole thing
		$sh->{Function}->{Domain}=PDFArray(PDFNum(0),PDFNum(1));

	}

	# Extend infinitely in both directions
	$sh->{Extend} = PDFArray( PDFBool(1), PDFBool(1) );

	return $sh;
}