From 0351d5af88ee4bde72b245f068ea0d6f2c79167c Mon Sep 17 00:00:00 2001 From: Brian Osman Date: Wed, 7 Apr 2021 16:01:52 -0400 Subject: [PATCH] Add user docs about Skia coordinate spaces Includes a general explanation of device vs. local, how shaders don't move with geometry, and how to use canvas transforms. Also shows localMatrix on an SkShader. Finally, links to that from the SkSL page, and adds SkSL-specific notes about coordinates. Bug: skia:11763 Change-Id: I31462aff66ff8514392098b972a10e7c96e4f254 Reviewed-on: https://skia-review.googlesource.com/c/skia/+/393516 Commit-Queue: Brian Osman Reviewed-by: Michael Ludwig --- site/docs/user/coordinates.md | 76 +++++++++++++++++++++++++++++++++++ site/docs/user/sksl.md | 16 +++++++- 2 files changed, 91 insertions(+), 1 deletion(-) create mode 100644 site/docs/user/coordinates.md diff --git a/site/docs/user/coordinates.md b/site/docs/user/coordinates.md new file mode 100644 index 0000000000..135692156e --- /dev/null +++ b/site/docs/user/coordinates.md @@ -0,0 +1,76 @@ +--- +title: 'Skia Coordinate Spaces' +linkTitle: 'Coordinates' +--- + +## Overview + +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. + +--- + +## Local Coordinates + +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`): + + + +--- + +## Shaders Do Not Move With Geometry + +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. + +--- + +## Transforming Local Coordinate Space + +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: + + + +--- + +## Transforming Shader Coordinate Space + +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: + + diff --git a/site/docs/user/sksl.md b/site/docs/user/sksl.md index 5350c20023..13b3589b12 100644 --- a/site/docs/user/sksl.md +++ b/site/docs/user/sksl.md @@ -81,4 +81,18 @@ by Skia clamping the color's RGB values to its alpha. ## Coordinate Spaces -Under construction +To understand how coordinates work in SkSL, you first need to understand +[how they work in Skia](/docs/user/coordinates). If you're comfortable with Skia's coordinate +spaces, then just remember that the coordinates supplied to your `main()` are **local** +coordinates. They will be relative to the coordinate space of the `SkShader`. This will match the +local space of the canvas and any `localMatrix` transformations. Additionally, if the shader is +invoked by another, that parent shader may modify them arbitrarily. + +In addition, the `SkShader` produced from an `SkImage` does not use normalized coordinates (like a +texture in GLSL). It uses `(0, 0)` in the upper-left corner, and `(w, h)` in the bottom-right +corner. Normally, this is exactly what you want. If you're sampling an `SkImageShader` with +coordinates based on the ones passed to you, the scale is correct. However, if you want to adjust +those coordinates (to do some kind of re-mapping of the image), remember that the coordinates are +scaled up to the dimensions of the image: + +