createRadialGradient (creates a path styling object)

suggest change

var gradient = createRadialGradient( 
      centerX1, centerY1, radius1,     // this is the "display' circle
      centerX2, centerY2, radius2      // this is the "light casting" circle
)
gradient.addColorStop(gradientPercentPosition, CssColor)
gradient.addColorStop(gradientPercentPosition, CssColor)
[optionally add more color stops to add to the variety of the gradient]

Creates a reusable radial gradient (object). The gradient object is an object that you can use (and reuse!) to make your path strokes and fills become gradient colored.

About…

The Canvas radial gradient is extremely different from traditional radial gradients.

The “official” (almost undecipherable!) definition of Canvas’s radial gradient is at the bottom of this posting. Don’t look at it if you have a weak disposition!!

In (almost understandable) terms:

The radial gradient has 2 circles: a “casting” circle and a “display” circle.
The casting circle casts light into the display circle.
That light is the gradient.
The shape of that gradient light is determined by the relative size and position of both circles.

Creating a gradient object is a 2-step process:

Create the gradient object itself. During creation you define a line on the canvas where the gradient will start and end. The gradient object is created with var gradient = context.radialLinearGradient.
Then add 2 (or more) colors that make up the gradient. This is done by adding multiple color stops to the gradient object with gradient.addColorStop.

Arguments:

centerX1,centerY1,radius1 defines a first circle where the gradient will be displayed.
centerX2,centerY2,radius2 defines a second circle which is casting gradient light into the first circle.
gradientPercentPosition is a float number between 0.00 and 1.00 assigned to a color stop. It is basically a percentage waypoint defining where this particular color stop applies along the gradient.
The gradient begins at percentage 0.00.
The gradient ends at percentage 1.00.
Technical note: The term “percentage” is not technically correct since the values go from 0.00 to 1.00 rather than 0% to 100%.
CssColor is a CSS color assigned to this particular color stop.

Side Note: The gradient object is not internal to the Canvas element nor it’s Context. It is a separate and reusable JavaScript object that you can assign to any Path you desire. You can even use this object to color a Path on a different Canvas element(!)

Color stops are (percentage) waypoints along the gradient line. At each color stop waypoint, the gradient is fully (==opaquely) colored with it’s assigned color. Interim points along the gradient line between color stops are colored as gradients of the this and the previous color.

Important hint about Canvas gradients!

When you create a gradient object, the entire radial gradient is “invisibly” cast upon the canvas.

When you stroke() or fill() a path, the invisible gradient is revealed, but only revealed over that path being stroked or filled.

If you create a green-to-red radial gradient like this:

// create a radialGradient
var x1=150;
var y1=150;
var x2=280;
var y2=150;
var r1=100;
var r2=120;
var gradient=ctx.createRadialGradient(x1,y1,r1,x2,y2,r2);
gradient.addColorStop(0,'red');
gradient.addColorStop(1,'green');
ctx.fillStyle=gradient;

Then Canvas will “invisibly” see your gradient creation like this:
But until you stroke() or fill() with the gradient, you will see none of the gradient on the Canvas.
Finally, if you stroke or fill a path using the gradient, the “invisible” gradient becomes visible on the Canvas … but only where the path is drawn.

<!doctype html>
<html>
<head>
<style>
    body{ background-color:white; padding:10px; }
    #canvas{border:1px solid blue; }
</style>
<script>
window.onload=(function(){

    // canvas related vars
    var canvas=document.getElementById("canvas");
    var ctx=canvas.getContext("2d");
    
    // create a radial gradient
    var x1=150;
    var y1=175;
    var x2=350;
    var y2=175;
    var r1=100;
    var r2=40;
    x2=x1;
    var gradient=ctx.createRadialGradient(x1,y1,r1,x2,y2,r2);
    gradient.addColorStop(0,'red');
    gradient.addColorStop(1,'green');
    ctx.fillStyle=gradient;

    // fill a path with the gradient
    ctx.beginPath();
    ctx.moveTo(150,0);
    ctx.lineTo(300,150);
    ctx.lineTo(150,325);
    ctx.lineTo(0,150);
    ctx.lineTo(150,0);
    ctx.fill();

}); // end window.onload
</script>
</head>
<body>
    <canvas id="canvas" width=300 height=325></canvas>
</body>
</html>

The scary official details

Who decides what `createRadialGradient does?

The W3C issues the official recommended specifications that browsers use to build the Html5 Canvas element.

The W3C specification for createRadialGradient cryptically reads like this:

What does createRadialGradient create

createRadialGradient … effectively creates a cone, touched by the two circles defined in the creation of the gradient, with the part of the cone before the start circle (0.0) using the color of the first offset, the part of the cone after the end circle (1.0) using the color of the last offset, and areas outside the cone untouched by the gradient (transparent black).

How does it work internally

The createRadialGradient(x0, y0, r0, x1, y1, r1) method takes six arguments, the first three representing the start circle with origin (x0, y0) and radius r0, and the last three representing the end circle with origin (x1, y1) and radius r1. The values are in coordinate space units. If either of r0 or r1 are negative, an IndexSizeError exception must be thrown. Otherwise, the method must return a radial CanvasGradient initialized with the two specified circles.

Radial gradients must be rendered by following these steps:

If x0 = x1 and y0 = y1 and r0 = r1, then the radial gradient must paint nothing. Abort these steps.
Let x(ω) = (x1-x0)ω + x0; Let y(ω) = (y1-y0)ω + y0; Let r(ω) = (r1-r0)ω + r0 Let the color at ω be the color at that position on the gradient (with the colors coming from the interpolation and extrapolation described above).
For all values of ω where r(ω) > 0, starting with the value of ω nearest to positive infinity and ending with the value of ω nearest to negative infinity, draw the circumference of the circle with radius r(ω) at position (x(ω), y(ω)), with the color at ω, but only painting on the parts of the canvas that have not yet been painted on by earlier circles in this step for this rendering of the gradient.

Found a mistake? Have a question or improvement idea? Let me know.

Table Of Contents