Skia generally refers to two different coordinate spaces: device and local. Device coordinates are defined by the surface (or other device) that you're rendering to. They range from (0, 0) in the upper-left corner of the surface, to (w, h) in the bottom-right corner - they are effectively measured in pixels.
The local coordinate space is how all geometry and shaders are supplied to the SkCanvas. By default, the local and device coordinate systems are the same. This means that geometry is typically specified in pixel units. Here, we position a rectangle at (100, 50), and specify that it is 50 units wide and tall:
Local coordinates are also used to define and evaluate any SkShader on the paint. Here, we define a linear gradient shader that goes from green (when x == 0) to blue (when x == 50):
Now, let's try to draw the gradient-filled square at (100, 50):
What happened? Remember, the local coordinate space has not changed. The origin is still in the upper-left corner of the surface. We have specified that the geometry should be positioned at (100, 50), but the SkShader is still producing a gradient as x goes from 0 to 50. We have slid the rectangle across the gradient defined by the SkShader. Shaders do not move with the geometry.
To get the desired effect, we could create a new gradient shader, with the positions moved to 100 and 150. That makes our shaders difficult to reuse. Instead, we can use methods on SkCanvas to change the local coordinate space. This causes all local coordinates (geometry and shaders) to be evaluated in the new space defined by the canvas' transformation matrix:
Finally, it is possible to transform the coordinate space of the SkShader, relative to the canvas local coordinate space. To do this, you supply a localMatrix parameter when creating the SkShader. In this situation, the geometry is transformed by the SkCanvas matrix. The SkShader is transformed by the SkCanvas matrix and the localMatrix for that shader. The other way to think about this: The localMatrix defines a transform that maps the shader's coordinates to the coordinate space of the geometry.
To help illustrate the difference, here‘s our gradient-filled box. It’s first been translated 50 units over and down. Then, we apply a 45 degree rotation (pivoting on the center of the box) to the canvas. This rotates the geometry of the box, and the gradient inside it:
Compare that to the second example. We still translate 50 units over and down. Here, though, we apply the 45 degree rotation only to the shader, by specifying it as a localMatrix to the SkGradientShader::MakeLinear function. Now, the box remains un-rotated, but the gradient rotates inside the box: