| Shapes | Bézier Curves |
|---|---|
|
|
|
| Translations and Rotations | Text Rendering |
|
|
|
| Discrete Path Effects | Composed Path Effects |
|
|
|
| Sum Path Effects | Shaders |
|
|
|
Triangle $\triangle C_f C P$ is similar to triangle $\triangle C_f C_1 P_1$.
Therefore $||P C|| = ||P_1 C_1|| \cdot (||C_f C|| / ||C_f C_1||) = r_1 x'$. Thus
$x'$ is a solution to $x_t$. Because triangle $\triangle C_f C P$ and triangle
$\triangle C_f C_1 P_1$ are similar,
$x'
= ||C_f C_1|| \cdot (||C_f P|| / ||C_f P_1||) = ||C_f P|| / ||C_f P_1||$.
$\square$
**Lemma 2.** For every solution $x_t$, if we extend/shrink segment $C_f P$ to
$C_f P_1$ with ratio $1 / x_t$ (i.e., find $P_1$ on ray $C_f P$ such that
$||C_f P_1|| / ||C_f P|| = 1 / x_t$), then $P_1$ must be on circle $C_1, r_1$.
_Proof._ Let $C_t = (x_t, 0)$. Triangle $\triangle C_f C_t P$ is similar to
$C_f C_1 P_1$. Therefore $||C_1 P_1|| = r_1$ and $P_1$ is on circle $C_1, r_1$.
$\square$
**Corollary 1.** By lemma 1. and 2., we conclude that the number of solutions
$x_t$ is equal to the number of intersections between ray $C_f P$ and circle
$C_1, r_1$. Therefore
- when $r_1 > 1$, there's always one unique intersection/solution; we call this
"well-behaved"; this was previously known as the "inside" case;
- when $r_1 = 1$, there's either one or zero intersection/solution (excluding
$C_f$ which is always on the circle); we call this "focal-on-circle"; this was
previously known as the "edge" case;
- when $r_1 < 1$, there may be $0, 1$, or $2$ solutions; this was also
previously as the "outside" case.
**Lemma 3.** When solutions exists, one such solution is
$$
x_t = {|| C_f P || \over ||C_f P_1||} = \frac{x^2 + y^2}{x + \sqrt{(r_1^2 - 1) y^2 + r_1^2 x^2}}
$$
_Proof._ As $C_f = (0, 0), P = (x, y)$, we have $||C_f P|| = \sqrt{x^2 + y^2}$.
So we'll mainly focus on how to compute $||C_f P_1||$.
**When $x \geq 0$:**
Let $X_P = (x, 0)$ and $H$ be a point on $C_f P_1$ such that $C_1 H$ is
perpendicular to $C_f
P_1$. Triangle $\triangle C_1 H C_f$ is similar to triangle
$\triangle P X_P C_f$. Thus
$$||C_f H|| = ||C_f C_1|| \cdot (||C_f X_P|| / ||C_f P||) = x / \sqrt{x^2 + y^2}$$
$$||C_1 H|| = ||C_f C_1|| \cdot (||P X_P|| / ||C_f P||) = y / \sqrt{x^2 + y^2}$$
Triangle $\triangle C_1 H P_1$ is a right triangle with hypotenuse $r_1$. Hence
$$ ||H P_1|| = \sqrt{r_1^2 - ||C_1 H||^2} = \sqrt{r_1^2 - y^2 / (x^2 + y^2)} $$
We have \begin{align} ||C_f P_1|| &= ||C_f H|| + ||H P_1|| \\\\\\ &= x /
\sqrt{x^2 + y^2} + \sqrt{r_1^2 - y^2 / (x^2 + y^2)} \\\\\\ &= \frac{x +
\sqrt{r_1^2 (x^2 + y^2) - y^2}}{\sqrt{x^2 + y^2}} \\\\\\ &= \frac{x +
\sqrt{(r_1^2 - 1) y^2 + r_1^2 x^2}}{\sqrt{x^2 + y^2}} \end{align}
**When $x < 0$:**
Define $X_P$ and $H$ similarly as before except that now $H$ is on ray $P_1 C_f$
instead of $C_f P_1$.
As before, triangle $\triangle C_1 H C_f$ is similar to triangle
$\triangle P X_P C_f$, and triangle $\triangle C_1 H P_1$ is a right triangle,
so we have
$$||C_f H|| = ||C_f C_1|| \cdot (||C_f X_P|| / ||C_f P||) = -x / \sqrt{x^2 + y^2}$$
$$||C_1 H|| = ||C_f C_1|| \cdot (||P X_P|| / ||C_f P||) = y / \sqrt{x^2 + y^2}$$
$$ ||H P_1|| = \sqrt{r_1^2 - ||C_1 H||^2} = \sqrt{r_1^2 - y^2 / (x^2 + y^2)} $$
Note that the only difference is changing $x$ to $-x$ because $x$ is negative.
Also note that now $||C_f P_1|| = -||C_f H|| + ||H P_1||$ and we have
$-||C_f H||$ instead of $||C_f H||$. That negation cancels out the negation of
$-x$ so we get the same equation of $||C_f P_1||$ for both $x \geq 0$ and
$x < 0$ cases:
$$
||C_f P_1|| = \frac{x + \sqrt{(r_1^2 - 1) y^2 + r_1^2 x^2}}{\sqrt{x^2 + y^2}}
$$
Finally
$$
x_t = \frac{||C_f P||}{||C_f P_1||} = \frac{\sqrt{x^2 + y^2}}{||C_f P_1||}
= \frac{x^2 + y^2}{x + \sqrt{(r_1^2 - 1) y^2 + r_1^2 x^2}}
$$ $\square$
**Corollary 2.** If $r_1 = 1$, then the solution
$x_t = \frac{x^2 + y^2}{(1 + r_1) x}$, and it's valid (i.e., $x_t > 0$) iff
$x > 0$.
_Proof._ Simply plug $r_1 = 1$ into the formula of Lemma 3. $\square$
**Corollary 3.** If $r_1 > 1$, then the unique solution is
$x_t = \left(\sqrt{(r_1^2 - 1) y ^2 + r_1^2 x^2} - x\right) / (r_1^2 - 1)$.
_Proof._ From Lemma 3., we have
\begin{align}
x_t &= \frac{x^2 + y^2}{x + \sqrt{(r_1^2 - 1) y^2 + r_1^2 x^2}} \\\\\\
&= {
(x^2 + y^2) \left ( -x + \sqrt{(r_1^2 - 1) y^2 + r_1^2 x^2} \right )
\over
\left (x + \sqrt{(r_1^2 - 1) y^2 + r_1^2 x^2} \right )
\left (-x + \sqrt{(r_1^2 - 1) y^2 + r_1^2 x^2} \right )
} \\\\\\
&= {
(x^2 + y^2) \left ( -x + \sqrt{(r_1^2 - 1) y^2 + r_1^2 x^2} \right )
\over
-x^2 + (r_1^2 - 1) y^2 + r_1^2 x^2
} \\\\\\
&= {
(x^2 + y^2) \left ( -x + \sqrt{(r_1^2 - 1) y^2 + r_1^2 x^2} \right )
\over
(r_1^2 - 1) (x^2 + y^2)
} \\\\\\
&= \left(\sqrt{(r_1^2 - 1) y ^2 + r_1^2 x^2} - x\right) / (r_1^2 - 1)
\end{align}
The transformation above (multiplying $-x + \sqrt{(r_1^2 - 1) y^2 + r_1^2 x^2}$
to enumerator and denominator) is always valid because $r_1 > 1$ and it's the
unique solution due to Corollary 1. $\square$
**Lemma 4.** If $r_1 < 1$, then
1. there's no solution to $x_t$ if $(r_1^2 - 1) y^2 + r_1^2 x^2 < 0$
2. otherwise, the solutions are
$x_t = \left(\sqrt{(r_1^2 - 1) y ^2 + r_1^2 x^2} - x\right) / (r_1^2 - 1)$,
or
$x_t = \left(-\sqrt{(r_1^2 - 1) y ^2 + r_1^2 x^2} - x\right) / (r_1^2 - 1)$.
(Note that solution $x_t$ still has to be nonnegative to be valid; also note
that $x_t > 0 \Leftrightarrow x > 0$ if the solution exists.)
_Proof._ Case 1 follows naturally from Lemma 3. and Corollary 1.
For case 2, we notice that $||C_f P_1||$ could be
1. either $||C_f H|| + ||H P_1||$ or $||C_f H|| - ||H P_1||$ if $x \geq 0$,
2. either $-||C_f H|| + ||H P_1||$ or $-||C_f H|| - ||H P_1||$ if $x < 0$.
By analysis similar to Lemma 3., the solution to $x_t$ does not depend on the
sign of $x$ and they are either
$\frac{x^2 + y^2}{x + \sqrt{(r_1^2 - 1) y^2 + r_1^2 x^2}}$ or
$\frac{x^2 + y^2}{x - \sqrt{(r_1^2 - 1) y^2 + r_1^2 x^2}}$.
As $r_1 \neq 1$, we can apply the similar transformation in Corollary 3. to get
the two formula in the lemma. $\square$
---
### Site Docs Dev Design Raster Tragedy Index (`site/docs/dev/design/raster_tragedy/_index.md`)
---
title: "The Raster Tragedy in Skia"
linkTitle: "The Raster Tragedy in Skia"
---
This is an extension of [The Raster Tragedy at Low-Resolution Revisited](http://rastertragedy.com)
as it applies to Skia. The Raster Tragedy describes a number of issues with typeface rasterization
with a particular emphasis on proper hinting to overcome these issues. Since not all fonts
are nicely hinted and sometimes hinting is not desired, there are additional hacks which may
be applied. Generally, one wants to hint purely informational text laid out for a particular
device, but not hint text which is art. Unless, of course, the hinting is part of the art like
Shift_JIS art.
The Gamma Hack
--------------
First, one should be aware of transfer functions (of which 'gamma' is an
example). A good introduction can be had at [What Every Coder Should Know About
Gamma](https://blog.johnnovak.net/2016/09/21/what-every-coder-should-know-about-gamma/).
In Skia, all color sources are converted into the destination color space and the blending is done
in the destination color space by applying the linear blend function. Skia does not convert into
a linear space, apply the linear blend, and convert back to the encoded space. If the destination
color space does not have a linear encoding this will lead to 'incorrect' blending. The idea is
that there are essentially two kinds of users of Skia. First there are existing systems which
are already using a non-linear encoding with a linear blend function. While the blend isn't
correct, these users generally don't want anything to change due to expectations. Second there
are those who want everything done correctly and they are willing to pay for a linearly encoded
destination in which the linear blend function is correct.
For bi-level glyph rendering a pixel is either covered or not, so there are no coverage blending
issues.
For regular full pixel partial coverage (anti-aliased) glyph rendering the user may or may not
want correct linear blending. In most non-linear encodings, using the linear blend function
tends to make black on white look slightly heavier, using the pixel grid as a kind of contrast
and optical sizing enhancement. It does the opposite for white on black, often making such
glyphs a bit under-covered. However, this fights the common issue of blooming where light on
dark on many displays tends to appear thicker than dark on light. (The black not being fully
black also contributes.) If the pixels are small enough and there is proper optical sizing and
perhaps anti-aliased drop out control (these latter two achieved either manually with proper
font selection or 'opsz', automatically, or through hinting) then correct linear blending tends
to look great. Otherwise black on white text tends to (correctly) get really anemic looking at
small sizes. So correct blending of glyph masks here should be left up to the user of Skia. If
they're really sophisticated and already tackled these issues then they may want linear blending
of the glyphs for best effect. Otherwise the glyphs should just keep looking like they used to
look due to expectations.
For subpixel partial coverage (subpixel anti-aliased) glyph masks linear blending in a
linear encoding is more or less required to avoid color fringing effects. The intensity of
the subpixels is being directly exploited so needs to be carefully controlled. The subpixels
tend to alleviate the issues with no full coverage (though still problematic if blitting text
in one of the display's primaries). One will still want optical sizing since the glyphs will
still look somewhat too light when scaled down linearly.
So, if subpixel anti-aliased glyph masks (and sometimes full pixel anti-aliased glyph masks)
need a correct blit how are they to be used with non-linearly encoded destinations?
One possible solution is to special case these blits. If blitting on the CPU it's often fast and
close enough to take the square root of the source and destination values, do the linear blend
function, then square the result (approximating the destination encoding as if its transfer
function is square). Many GPUs have a mode where they can blend in sRGB, though unfortunately
this generally applies to the whole framebuffer, not just individual draws. For various reasons,
Skia has avoided special casing these blends.
What Skia currently does is the gamma hack. When creating the glyph mask one usually knows
the approximate color which is going to be drawn, the transfer function, and that a linear
source-over blend is going to be used. The destination color is then guessed to be a contrasting
color (if there isn't any contrast the drawing won't be able to be seen anyway) so assume that the
destination color will be the perceptually opposite color in the destination color space. One can
now determine the desired value by converting the perceptual source and guessed destination into
a linear encoding, do the linear source-over blend, and convert to the destination encoding. The
coverage is then adjusted so that the result of a linear source-over blend on the non-linear
encoded values will be as close as possible to this desired value.
This works, but makes many assumptions. The first is the guess at the destination. A perceptual
middle gray could equally well (or poorly) contrast with black or white so the best guess
is drawing it on top of itself. Subpixel anti-aliased glyph masks drawn with this guess will
be drawn without any adjustment at all, leaving them color fringy. On macOS Skia tweaks the
destination guess to reduce the correction when using bright sources. This helps reducing
'blooming' issues with light on dark (aka dark mode) and better matches how CoreText seems
to do blending. The second is that a src-over blend is assumed, but users generally aren't as
discriminating of the results of other blends.
The gamma hack works best with subpixel anti-aliasing since the adjustment can be made per-channel
instead of full pixel. If this hack is applied to full pixel anti-aliased masks everything is
essentially being done in the nearest gray instead of the nearest color (since there is only
one channel through which to communicate), leading to poor results. Most users will not want
the gamma hack applied to full pixel anti-aliased glyphs.
Since the gamma hack is logically part of the blend, it must always be the very last adjustment
made to the coverage mask before being used by the blitter. The inputs are the destination
transfer function and the current color (in the destination color space). In Skia these come
from the color space on the SkSurface and the color on the SkPaint.
Optical Sizing Hack
-------------------
In metal type a type designer will draw out on paper the design for the faces of the final
sorts. Often there would be different drawings for different target sizes. Sometimes these
different sizes look quite different (like Display and Text faces of the same family). Then a
punch cutter takes these drawings and creates a piece of metal called a punch which can stamp
out these faces. The punch is used to create a negative in a softer piece of metal forming a
strike. This strike is made the correct width and called a matrix. This matrix is used as a mold
to cast individual sorts. The sorts are collected into a box called a type case. A typesetter
would take sorts from a type case and set them into a form. The printer would then ink the
sorts in the form and press the paper. (Note that the terms 'typeface' and 'font' aren't used
in this description, there is a lot of disagreement on what they apply to.)
Every step of this process is now automated in some way. Unfortunately, knowledge embedded in
the manual process has not always been replicated in the automation. This can be for a wide
variety of reasons, such as being overlooked or being difficult to emulate. One of these areas
is the art of optical sizing and managing thin features.
In general smaller type should be relatively heavier in weight than would be expected if taking
a larger size and linearly scaling it down. The type designer will draw out the faces with this
in mind, potentially with an eye toward how it would vary with size and with potential need
for ink traps. The punch cutter would then cut the punches at a given size with this in mind,
adjusting until the soot proofs looked good. There may even be slight adjustments to the matrix
itself if something seemed off. The typesetter would often know which specific cases contained
slightly heavier or lighter sorts. The printer would then adjust the ink and pressure to get
a good looking print.
Popular digital font formats didn't really support this until recently with the variable font
'opsz' axis. The presence of an 'opsz' axis is like the type designer giving really good
instructions about how the faces should look at various sizes. However, not all fonts have or
will have a 'opsz' axis. Since we don't always have an 'opsz' what can be done to prevent small
glyphs from looking all washed out?
One way the type designer could influence the optical size is through hinting. Any manual
hinting is done by someone looking at the result at small sizes. Tweaks are made until it
'looks good'. This often unconsciously bakes in optical sizing. Even autohinters eventually
end up emulating this, generally making the text more contrasty and somewhat heavier at small
pixel sizes (this depends on the target pixel size not the nominal requested size).
An alternate way the designer could provide optical sized fonts is using multiple font files
for different optical sizes and expect the user to select the right one (like Display and
Text variants). In theory the right one might also be selected automatically based on some
criteria. Switching font files because of nominal size changes may seem drastic, but this is
how the system font on macOS worked for a while.
One automatic way to do optical sizing is to artificially embolden the outline itself at small
nominal sizes. This is the approach taken by CoreText. This is a lot like the dreaded fake-bold,
but doesn't have the issue of the automatic fake bolding being heavier than ultra bold, since
this emboldening is applied uniformally based on requested nominal size.
Another automatic way to do optical sizing is to over-cover all the edges when doing
anti-aliasing. The pixels are a fixed physical size so affect small features more than large
features. Skia currently has rudimentary support for this in its 'contrast hack' which is
described more later.
As a note on optical sizing, this is one place where the nominal or optical size of the font is
treated differently from the final pixel size of the font. A SkCanvas may have a scale transform
active. Any hinting will be done at the final pixel size (the font size mapped through the
current transformation matrix), but the optical size is not affected by the transform since
it's actually a parameter for the SkTypeface (and maybe the SkFont).
The Contrast Hack
-----------------
Consider the example of [a pixel wide stroke at half-pixel
boundaries](http://rastertragedy.com/RTRCh3.htm#Sec1). As stated in section 3.1.3 "if we were
to choose the stroke positions to render the most faithful proportions and advance width, we
may have to compromise the rendering contrast." If the stroke lands on a pixel boundary all
is well. If the stoke lands at a half pixel boundary and correct linear blending is used then
the same number of photons are reaching the eye, but the reduction in photons is spread out
over twice the area. If the pixels were small enough then this wouldn't be an issue. Back of
the envelope suggests an 8K 20inch desktop monitor or ~400ppi being the minimum. Note that RGB
subpixel anti-aliasing brings a 100dpi display up to 300dpi, which is close, but still a bit
short. Exploiting the RGB subpixels also doesn't really increase the resolution as much when
getting close to the RGB primaries for the fill color.
One way to try to compensate for this is to cover some of these partially covered pixels more
until it visually looks better. Note that this depends on a lot of factors like the pixel density
of the display, the visual acuity of the user, the distance of the user from the display, and the
user's sensitivity to the potential variations in stem darkness which may result. Automatically
taking all these factors into account would be quite difficult. The correct function is generally
determined by having the user look at the result of applying various amounts of extra coverage
and having them to pick a setting that looks the least bad to them.
This specific form of over-covering is a form of drop out control for anti-aliasing and could
be implemented in a similar way, detecting when a stem comes on in one pixel and goes out in
the next and mark that for additional coverage. At raster time a cruder approximation could be
made by doing a pass in each of the horizontal and vertical directions and finding runs of more
than one non-fully-covered pixel and increasing their coverage.
If instead of doing these computationally expensive passes all coverage is boosted then in
addition to the smeared stems the entire outside edge of the glyph will also be bolded. Making
these outside edges heavier is a crude approximation of outsetting the initial path in a
rather complicated way and amounts to an optical sizing tweak. Just as hinting can be used to
approximate optical sizing if the user's perception of the pixel sizes is known in advance,
this is a pixel level tweak tied to a specific user and display combination.
Much like the gamma hack can be modified to reduce the correction for light on dark to
fight blooming, the contrast hack can be reduced when the color being drawn is known to be
light. Generally the contrast correction goes to zero as one approaches white.
---
### Architecture CPU (`docs/architecture/CPU.md`)
# Skia CPU Backend Architecture
This document outlines the major pieces of Skia's CPU backend. The CPU backend is responsible for
rendering graphics on the CPU, without the use of a GPU.
## Background and Definitions
* **Bitmap**: A grid of pixels representing an image, where each pixel has a color. This is the
digital canvas Skia's CPU backend paints on. Common image file formats like PNG and JPEG store
bitmap data.
* **Blend Mode**: A rule that defines how a source color (the one being drawn) is mathematically
combined with a destination color (the one already on the canvas).
* **Blitter**: A component that writes the final pixel colors from the rendering pipeline into the
destination bitmap. It's the "hand" that actually puts the colored pixels onto the canvas.
* **Clip**: A region that restricts drawing. Anything drawn outside the clip is not visible.
* **Coverage Mask**: An array of values (typically 8-bit alpha) that represents how much a
geometric shape covers each pixel. A value of 255 means fully covered, 0 means not covered,
and intermediate values represent partial coverage for anti-aliasing.
* **Hairline**: The thinnest visual line, typically one device pixel wide. A stroke width of 0
in a paint is interpreted as a hairline. Hairlines do not scale with the CTM.
* **Matrix**: A mathematical tool used to transform (translate, scale, rotate, skew) what is
being drawn.
* **Paint**: An object holding stylistic information for drawing, like color, stroke width, and
effects.
* **Path**: A sequence of lines and curves that describe a shape. Skia uses quadratic, cubic, and
conic Bézier curves to create smooth, scalable curves. A quadratic curve has one control point,
while a cubic curve has two for more complex shapes. A conic curve represents perfect
circles etc using one control point and one weight.
* **Rasterization**: Converting vector graphics (math-based shapes) into a grid of pixels (a
raster image) for display.
* **Scanline**: A single horizontal row of pixels. Complex shapes are often rendered one scanline
at a time.
* **Shader**: A program that calculates the color of a pixel. Shaders can produce solid colors,
gradients, textures, or procedural patterns.
* **Tiling**: An optimization strategy where a large drawing operation is broken into a series of
smaller, tile-sized operations to keep memory usage (e.g., for intermediate buffers) bounded.
* **Winding Number**: An algorithm used to determine if a point is inside a complex or
self-intersecting path. Imagine drawing a ray from the point in any fixed direction to
infinity. The winding number is the count of how many times the path crosses the ray in one
direction (e.g., clockwise) minus the number of times it crosses in the other direction
(counter-clockwise). For a non-zero winding rule, any point with a non-zero winding number is
considered "inside" the path. This correctly handles shapes with holes and overlapping
sections.
## Data Flow Walkthrough
The following sections describe the journey of a single drawing command (e.g.,
`canvas.drawPath(...)`) through the CPU backend, from the public API call to modifying raw pixel
memory.
See [CPU.dot](./CPU.dot) for a supplementary diagram.
### 1. The API Layer
The journey begins with the user-facing drawing API.
- **`SkSurface`**: Represents the drawing destination. A CPU-backed surface, created via
**`SkSurfaces::Raster(...)`**, allocates and owns pixel memory via an `SkPixelRef`. The
`SkSurface` manages an `SkBitmap` using this memory and provides an `SkCanvas` for drawing.
- **`SkImage`**: Represents an immutable snapshot of pixel data. It can be created from an
`SkSurface` (via `surface->makeImageSnapshot()`), from an `SkBitmap`, or from encoded data
(e.g., a PNG file). On the CPU backend, this is implemented by **`SkImage_Raster`**, which holds
an `SkBitmap` that in turn points to the underlying pixels via an `SkPixelRef`. Because it is
immutable, it can be cached and shared safely across threads. It can be drawn to a canvas via
`canvas->drawImage(...)`.
- **`SkCanvas`**: The primary drawing interface with methods like `drawPath`, `drawImage`, etc. The
user provides geometry (e.g., `SkPath`), images (`SkImage`), styling (`SkPaint`), and font
information (`SkFont`) to the canvas. The `SkCanvas` holds the current transformation matrix
and clip. When a draw call is made, the `SkCanvas` forwards all the information to an internal
`SkDevice` for rendering.
- **`SkPath`**: A high-level object representing vector geometry (lines, curves). It is a
lightweight, copy-on-write object that holds a shared pointer (`sk_sp`) to an `SkPathRef`.
- **`SkPathRef`**: The reference-counted object that actually stores the raw path data: arrays of
points, verbs (move, line, quad, conic, cubic, close), and conic weights. `SkPathRef` objects are
always **heap-allocated** and managed by `sk_sp`. Internally, `SkPathRef` uses
`skia_private::STArray` for its geometry data storage. This `STArray` is a small-object optimized
array, meaning that for small paths, the geometry data is stored directly within the `STArray`'s
internal buffer (part of the heap-allocated `SkPathRef` object). For larger paths, the `STArray`
dynamically allocates additional memory on the heap to store the geometry data.
#### Text Rendering
Drawing text is a specialized, but common, case. The process involves three key classes:
- **`SkFontMgr`**: A top-level object that discovers and manages the fonts installed on the system.
It is used to create an `SkTypeface` by matching a font family name (e.g., "Roboto") or by
loading font data directly from a file or stream. It also handles "fallback", which allows a user
to find the data to draw a glyph from a collection of fonts and ordering heuristics (e.g. use this
font for Latin characters and this font for emoji).
- **`SkTypeface`**: An immutable object representing the raw data of a single font face (e.g.,
"Roboto Bold"). It typically contains the vector paths for each glyph, but also supports bitmap
glyphs. Vector glyphs are rasterized and stored in a glyph cache (`SkStrikeCache`).
- **`SkFont`**: A lightweight object that holds a reference to an `SkTypeface` plus styling
attributes like text size, scale, and skew.
When a user calls a method like `canvas.drawSimpleText(...)`, they provide the text and an `SkFont`
to the `SkCanvas`. The backend then uses the `SkFont` to look up the individual glyphs from the
`SkTypeface`. Each glyph is subsequently treated as a standard `SkPath` to be rendered.
**Note on Text Layout:** Core Skia handles rendering individual glyphs, but it does not perform
complex text layout (e.g., line breaking, justification, or bidirectional text). For rich text
layout, Skia provides the **`SkParagraph`** module, which is a higher-level library built on top
of Skia's core components.
#### Paint Configuration
The **`SkPaint`** object holds a suite of optional components that control the styling and
pixel-processing pipeline.
- **`SkShader`**: Generates the source color for the geometry. If no shader is present, the paint's
color is used. Shaders can produce gradients, bitmap patterns, or procedural colors.
- **`SkColorFilter`**: Modifies the source color produced by the shader or paint. Common uses
include tinting or applying a color matrix for color correction.
- **`SkMaskFilter`**: Operates on the shape's coverage mask, not its color. Its most common use is
blurring the shape's edges, such as with a Gaussian blur from `SkMaskFilter::MakeBlur`.
- **`SkPathEffect`**: Modifies the geometry of a shape before it is drawn. For example,
`SkPathEffect::MakeDash` creates an effect that turns solid lines into dashed lines. This
happens before rasterization.
- **`SkBlender`**: Controls how the source color (from the shader) is blended with the destination
color (already on the canvas). It is a more powerful, programmable version of the traditional
`SkBlendMode` enum. The blending logic is executed as a stage in the `SkRasterPipeline`.
- **`SkImageFilter`**: Applies a complex, multi-pass effect to the output of a drawing operation.
Unlike other effects, an image filter can operate on the entire result of a draw as a texture.
This often requires allocating a temporary, offscreen layer. For example, a drop shadow filter
might draw the shape into a layer, blur it, offset it, and then draw the original shape again
on top of the blurred shadow.
### 2. The Device Layer: `SkBitmapDevice`
For the CPU backend, the `SkCanvas` forwards draw calls to an **`SkBitmapDevice`**. This object is
the concrete target for all CPU-based drawing. It manages the destination **`SkBitmap`** and
initiates rendering by creating and dispatching to an `SkDraw` object.
**A Note on Clipping:** The device manages an `SkRasterClipStack` corresponding to the canvas's
`save()`/`restore()` calls. For each draw, it resolves this stack into a single `SkRasterClip`
and passes it to `SkDraw`, which is stateless regarding the clip.
**A Note on Tiling:** For large or complex draws, the device may use tiling. It breaks the
operation into smaller, tile-sized chunks, adjusting the clip for each. This bounds the memory
required for intermediate buffers by invoking the draw process once per tile.
### 3. The Orchestrator: `SkDraw`
The `SkBitmapDevice` creates an **`SkDraw`** object for each primitive. `SkDraw` orchestrates a
single draw, bundling the geometry (`SkPath`), styling (`SkPaint`), transform, clip, and
destination `SkPixmap`. It uses `SkScan` to convert the vector shape into raster operations.
### 4. The Rasterizer: `SkScan`
`SkDraw` passes the `SkPath` to **`SkScan`**, the core rasterizer. `SkScan` converts the vector
path into horizontal scanlines, calculating a coverage mask (alpha values) for each. It is
unaware of color or effects. `SkDraw` provides `SkScan` with a `SkBlitter`, which `SkScan`
invokes for each scanline to render the coverage data.
**A Note on Scan Converters:** The `isAntiAlias()` flag on the `SkPaint` selects the scan
converter:
- **Aliased (`SkScan_Path.cpp`):** When anti-aliasing (AA) is off, it produces a binary (0% or
100%) coverage mask based on whether pixel centers are inside the path, resulting in hard
edges. For each horizontal run of covered pixels, it calls `blitter->blitH(x, y, width)`.
- **Analytic Anti-Aliased (`SkScan_AAAPath.cpp`):** When AA is on, it analytically calculates the
exact geometric area of intersection with each pixel, producing fractional coverage values for
smooth edges. For each horizontal run of partially-covered pixels, it calls
`blitter->blitAntiH(x, y, alphas, runs)`.
### 5. The Pixel Writer: `SkRasterPipelineBlitter`
The **`SkRasterPipelineBlitter`** is the primary `SkBlitter` in the CPU backend. It implements the
`SkBlitter` interface, but instead of writing pixels directly, it translates calls like `blitH`
or `blitRect` from `SkScan` into an execution of its internal `SkRasterPipeline`. It configures
the pipeline with the correct coverage information from the blitter call and then runs the
pipeline to compute and write the final pixel colors to those lines.
### 6. The Workhorse: `SkRasterPipeline`
The **`SkRasterPipeline`** calculates final pixel colors by chaining together single-purpose
**stages**. For example, a draw might use stages for loading coverage (`load_a8`), setting a
source color (`uniform_color`), loading the destination, blending (`srcover`), and storing the
result (`store_8888`). This stage-based design avoids a combinatorial explosion of functions.
The pipeline is assembled into a sequence of pre-compiled "stages", which are executed in a loop
over the covered area. These functions use **SIMD (e.g., SSE, NEON)** to process multiple pixels
at once for high performance. The pipeline gets memory layout information from an `SkPixmap` to
load and store pixels.
### 7. The Pixel Memory View: `SkPixmap`, `SkBitmap`, and `SkPixelRef`
This is the final stop where pixels are modified.
- **`SkPixmap`**: A lightweight object with a pointer to pixel memory and its metadata
(dimensions, color type). It provides the `SkRasterPipeline` with the exact memory addresses
for reading and writing.
- **`SkBitmap`**: Held by `SkBitmapDevice`, it pairs an `SkImageInfo` with the pixel storage.
- **`SkPixelRef`**: A smart pointer that owns the heap-allocated pixel memory, originally created
by the `SkSurface`.
The `SkRasterPipeline`'s final stage uses the address from the `SkPixmap` to write the new color
into the memory owned by the `SkPixelRef`, completing the draw.
---
### Site Docs Roles (`site/docs/roles.md`)
---
title: "Project Roles"
linkTitle: "Project Roles"
---
The Skia open source project includes individuals working in a variety of
roles. Anyone can view the code, use the Skia library, file bugs, and submit
patches. This page describes in detail the kinds of roles that interested
parties can assume.
For more information on ways to get involved in Skia development, see the
[Contributing to Skia page](/docs/dev/contrib/).
| Source Code & Documentation | Code Reviews | Bug Tracker | ||
|---|---|---|---|---|
| Committer |
force-commit |
approve changes |
||
| Contributor (and above) |
launch try jobs |
change bug status edit bug labels own bugs |
||
| Developer (and above) |
download view history |
commit changes (once approved) upload changes for approval view |
add comments to existing bugs file new bugs view bugs |
### Uploading changes for review
Skia uses the Gerrit code review tool. Skia's instance is
[skia-review](http://skia-review.googlesource.com). Use `git cl` to upload your
change:
git cl upload
You may have to enter a Google Account username and password to authenticate
yourself to Gerrit. A free gmail account will do fine, or any other type of
Google account. It does not have to match the email address you configured using
`git config --global user.email` above, but it can.
The command output should include a URL, similar to
([https://skia-review.googlesource.com/c/4559/](https://skia-review.googlesource.com/c/4559/)),
indicating where your changelist can be reviewed.
### Submit try jobs
Skia's trybots allow testing and verification of changes before they land in the
repo. You need to have permission to trigger try jobs; if you need permission,
ask a committer. After uploading your CL to
[Gerrit](https://skia-review.googlesource.com/), you may trigger a try job for
any job listed in tasks.json, either via the Gerrit UI, using `git cl try`, eg.
git cl try -B skia.primary -b Some-Tryjob-Name
or using bin/try, a small wrapper for `git cl try` which helps to choose try
jobs. From a Skia checkout:
bin/try --list
You can also search using regular expressions:
bin/try "Test.*Pixel.*Release"
For more information about testing, see
[testing infrastructure](/docs/dev/testing/automated_testing).
### Request review
Go to the supplied URL or go to the code review page and select the **Your**
dropdown and click on **Changes**. Select the change you want to submit for
review and click **Reply**. Enter at least one reviewer's email address. Now add
any optional notes, and send your change off for review by clicking on **Send**.
Unless you send your change to reviewers, no one will know to look at it.
_Note_: If you don't see editing commands on the review page, click **Sign in**
in the upper right. _Hint_: You can add -r reviewer@example.com --send-mail to
send the email directly when uploading a change using `git-cl`.
## The review process
If you submit a giant patch, or do a bunch of work without discussing it with
the relevant people, you may have a hard time convincing anyone to review it!
Code reviews are an important part of the engineering process. The reviewer will
almost always have suggestions or style fixes for you, and it's important not to
take such suggestions personally or as a commentary on your abilities or ideas.
This is a process where we work together to make sure that the highest quality
code gets submitted!
You will likely get email back from the reviewer with comments. Fix these and
update the patch set in the issue by uploading again. The upload will explain
that it is updating the current CL and ask you for a message explaining the
change. Be sure to respond to all comments before you request review of an
update.
If you need to update code the code on an already uploaded CL, simply edit the
code, commit it again locally, and then run git cl upload again e.g.
echo "GOATS" > whitespace.txt
git add whitespace.txt
git commit -m 'add GOATS fix to whitespace.txt'
git cl upload
Once you're ready for another review, use **Reply** again to send another
notification (it is helpful to tell the reviewer what you did with respect to
each of their comments). When the reviewer is happy with your patch, they will
approve your change by setting the Code-Review label to "+1".
_Note_: As you work through the review process, both you and your reviewers
should converse using the code review interface, and send notes.
Once your change has received an approval, you can click the "Submit to CQ"
button on the codereview page and it will be committed on your behalf.
Once your commit has gone in, you should delete the branch containing your
change:
git checkout -q origin/main
git branch -D my_feature
## Final Testing
Skia's principal downstream user is Chromium, and any change to Skia rendering
output can break Chromium. If your change alters rendering in any way, you are
expected to test for and alleviate this. You may be able to find a Skia team
member to help you, but the onus remains on each individual contributor to avoid
breaking Chrome.
### Evaluating Impact on Chromium
Keep in mind that Skia is rolled daily into Blink and Chromium. Run local tests
and watch canary bots for results to ensure no impact. If you are submitting
changes that will impact layout tests, follow the guides below and/or work with
your friendly Skia-Blink engineer to evaluate, rebaseline, and land your
changes.
Resources:
[How to land Skia changes that change Blink layout test results](/docs/dev/chrome/blink/)
If you're changing the Skia API, you may need to make an associated change in
Chromium. If you do, please follow these instructions:
[Landing Skia changes which require Chrome changes](/docs/dev/chrome/changes/)
## Check in your changes
### Non-Skia-committers
If you already have committer rights, you can follow the directions below to
commit your change directly to Skia's repository.
If you don't have committer rights in https://skia.googlesource.com/skia.git ...
first of all, thanks for submitting your patch! We really appreciate these
submissions. After receiving an approval from a committer, you will be able to
click the "Submit to CQ" button and submit your patch via the commit queue.
In special instances, a Skia committer may assist you in landing the change by
uploading a new codereview containing your patch (perhaps with some small
adjustments at their discretion). If so, you can mark your change as
"Abandoned", and update it with a link to the new codereview.
### Skia committers
- tips on how to apply an externally provided patch are [here](../patch)
- when landing externally contributed patches, please note the original
contributor's identity (and provide a link to the original codereview) in the
commit message
`git-cl` will squash all your commits into a single one with the description
you used when you uploaded your change.
```
git cl land
```
or
```
git cl land -c 'Contributor Name 
Follow that link to find the hash of the isolated outputs:
Then run `isolateserver.py` with --isolated set to that hash:
$ isolateserver.py \
download \
--isolate-server=https://isolateserver.appspot.com \
--isolated=5b85b7c382ee2a34530e33c7db20a07515ff9481 \
--target=./download/
---
### Site Docs Dev Testing Fonts (`site/docs/dev/testing/fonts.md`)
---
title: "Fonts and GM Tests"
linkTitle: "Fonts and GM Tests"
---
Overview
--------
Each test in the gm directory draws a reference image. Their primary purpose is
to detect when images change unexpectedly, indicating that a rendering bug has
been introduced.
The gm tests have a secondary purpose: they detect when rendering is different
across platforms and configurations.
GM font selection
-----------------
Each gm specifies the typeface to use when drawing text. To create a portable
typeface, use:
~~~~
SkTypeface* typeface = ToolUtils::CreatePortableTypeface(const char* name,
SkFontStyle style);
~~~~
---
### Site Docs Dev Testing Fuzz (`site/docs/dev/testing/fuzz.md`)
---
title: 'Fuzzing'
linkTitle: 'Fuzzing'
---
## Reproducing using `fuzz`
We assume that you can [build Skia](/docs/user/build). Many fuzzes only
reproduce when building with ASAN or MSAN; see
[those instructions for more details](../xsan).
When building, you should add the following args to BUILD.gn to make reproducing
less machine- and platform- dependent:
skia_use_fontconfig=false
skia_use_freetype=true
skia_use_system_freetype2=false
skia_use_wuffs=true
skia_enable_skottie=true
skia_enable_fontmgr_custom_directory=false
skia_enable_fontmgr_custom_embedded=false
skia_enable_fontmgr_custom_empty=true
All that is needed to reproduce a fuzz downloaded from ClusterFuzz or oss-fuzz
is to run something like:
out/ASAN/fuzz -b /path/to/downloaded/testcase
The fuzz binary will try its best to guess what the type/name should be based on
the name of the testcase. Manually providing type and name is also supported,
like:
out/ASAN/fuzz -t filter_fuzz -b /path/to/downloaded/testcase
out/ASAN/fuzz -t api -n RasterN32Canvas -b /path/to/downloaded/testcase
To enumerate all supported types and names, run the following:
out/ASAN/fuzz --help # will list all types
out/ASAN/fuzz -t api # will list all names
If the crash does not show up, try to add the flag --loops:
out/ASAN/fuzz -b /path/to/downloaded/testcase --loops 
Prerequisites
-------------
### Installing the profiler
To install the gperftool headers for compiling and the shared libraries for linking.
This includes `libprofiler.so` (for CPU) and `libtcmalloc.so` (for Heap).
# On Debian/Ubuntu:
$ sudo apt-get install libgoogle-perftools-dev
### Installing the visualizer
Googlers already have the `pprof` analysis tool, but external users can do the following to install `google-pprof` (and may want to make an alias to call it `pprof`).
# On Debian/Ubuntu:
$ sudo apt-get install google-perftools
Terminology
-----------
When analyzing profiles, you will see two primary metrics:
* **Flat**: Time (or memory) spent **strictly within** that specific function. High flat time indicates a bottleneck in the function's own logic (e.g., a heavy loop).
* **Cumulative**: Total time spent (or memory allocated) in that function *plus all functions it calls*. High cumulative time with low flat time indicates a bottleneck in one of the function's children.
Building with Profiling Support
-------------------------------
To enable the profiling instrumentation, set `skia_use_pprof=true` in your `args.gn`. It may help to use `-Og` to get accurate line-level attribution without sacrificing the performance benefits of optimization.
# Example args.gn in out/Profile
is_debug = false
skia_use_pprof = true
extra_cflags = ["-Og"]
Then build your target:
$ ninja -C out/Profile nanobench
This links in the CPU instrumenter (which will stop the program repeatedly and note where the program was running, aggregating the samples into the profile) and heap instrumenter (which keeps track of all allocations and frees).
Creating Profiles in Nanobench
------------------------------
When built with `skia_use_pprof`, `nanobench` provides flags to enable the profiler(s) to produce output.
## CPU Profiling
Use the `--cpuprofile` flag to specify the output filename. It is often useful to increase the duration of the run to get more samples.
$ ./out/Profile/nanobench --match 
$ pprof -web ./out/Profile/nanobench 
$ pprof -alloc_space -web ./out/Profile/nanobench output.heap.0005.heap
Without `-alloc_space`, only live bytes will be shown (unfreed memory). You can use any of the heap files, but it's probably most useful to see the latest one.
### Annotated Source
`pprof` can show how much time was spent on individual lines of code, even breaking down the assembly instructions. Due to instruction re-ordering, this isn't perfect (see Tips below). Large heap allocations can also muddy the performance blame.
$ pprof -weblist 
$ pprof -alloc_space -weblist 
$ pprof -flame ./out/Profile/nanobench 
## User Guide
SKP files can contain a single frame or multiple frames. Single frame files have
the .skp extension and Multi-frame files have the .mskp extension. In the online
debugger linked above, Open a [sample mskp file](/docs/dev/tools/calendar.mskp)
or capture one from an android device using the
[instructions here](https://sites.google.com/a/google.com/skia/android/skp-from-framework).
### Command Playback and Filters
Try playing back the commands within the current frame using the lower play
button 
, (the
one not in a circle) You should see the image built up one draw at a time.
Many commands manipulate the matrix or clip but don't make any visible change
when run. Try filtering these out by pasting
`!drawannotation save restore concat setmatrix cliprect` in to the filter
textbox just below the command playback controls. Press enter to apply the
filter, and resume playback if it was paused. This will have the effect of
making the playback appear to be much faster as there are only 29 commands in
the first frame of the sample file that pass this filter.
Try pausing command playback and stepping forward and back through the commands
using `,` (comma) and `.` (period).
> Filters are case insensitive, and the only supported logical operator is !
> (not) which applies to the entire filter and is only recognised when it occurs
> at the beginning.
Any command can be expanded using the
icon to see all of
the parameters that were recorded with that command.
Commands can be disabled or enabled with the checkbox that becomes available
after expanding the command's detail view.
Jog the command playhead to the end of the list with the
button.
### Frame playback
The sample file contains multiple frames. Use the encircled play button to play
back the frames. The current frame is indicated by the slider position, and the
slider can be set manually. Frames can be stepped through with `w` (back) and
`s` forward. `p` pauses or unpauses the frame playback.
Not all frames in a file will have the same number of commands. When the command
playhead is left at the end of the list the debugger will play every frame to
the end of its list. If the command playhead is somewhere in the middle, say
155, the debugger will try to play every frame to its 155th command.
### Resources Tab
Any resources that were referenced by commands in the file appear here. As of
Dec 2019, this only shows images.
Any resource can be selected and viewed. You may find it helpful to toggle the
Light/Dark setting if you cannot see an image.
Images' names are formatted as `7 @24205864 (99, 99)` where `7` is the index of
the image as it was saved in the file, `@24205864` is it's address in wasm
memory, for cross referencing with DrawImage\* commands in the command list
which also show this address, and `(99, 99)` is the size of the image.
The resource viewer allows a user to determine if an image was not effectively
shared between frames or draw commands. If it occurs more than once in the
resource tab, then there were multiple copies of it with different generation
ids in the process that recorded the SKP.
### Android Layers
When MSKPs are recorded in Android, Extra information about offscreen hardware
layers is recorded. The sample google calendar mskp linked above contains this
information. You will find two layers on frame 3.
There are two kinds of events relevant to recorded android layer use.
1. Draw Events - points when an offscreen surface was drawn to. They may be
complete, meaning the clip equalled the surface's size, or partial, meaning
the clip was smaller.
2. Use events - points when the offscreen surface was used as an SkImage in the
main surface.
Layers are shown as boxes in the bottom right of the interface when viewing a
frame where a layer draw event occurred. Each Layer box has two buttons:
`Show Use` will cycle through use events for that layer in the current frame if
there are any, and `Inspector` will open the draw event as if it were a single
frame SKP. you can play back it's commands, enable or disabled them, inspect GPU
op bounds or anything else you could do with an ordinary SKP. Exit the inspector
by clicking the `Exit` button on the layer box.
### Crosshair and Breakpoints
Clicking any point in the main view will toggle a red crosshair for selecting
pixels. the selected pixel's color is shown in several formats on the right
pane. A zoomed view centered on the selected pixel is shown below it. The
position can be moved precisely by either clicking neighboring pixels in the
zoom view, or using `H` (left) `L` (right) `J` (down) `K` (up).
When "Break on change" is selected, command playback will pause on any command
which changes the color of the selected pixel. this can be used to find the
command that draws something you see in the viewer.
### GPU Op Bounds and Other settings
Each of the filtered commands from above has a colored number to its right
. This is the GPU
operation id. When multiple commands share a GPU op id, this indicates that they
were batched together when sent to the GPU. In the WASM debugger, this goes
though WebGL.
There is a "Display GPU Op Bounds" toggle in the upper right of the interface.
Turning this on will show a colored rectangle to represent the bounds of the GPU
op of the currently selected command.
GPU - Controls which backend Skia uses to draw to the screen. GPU in the online
wasm debugger means WebGL. CPU means skia draws into a surface in memory which
is copied into an HTML canvas without using the GPU.
Light/Dark - this toggle changes the appearance of the checkerboard behind the
main view and zoom views to assist in viewing content with transparency.
Display Overdraw Viz - This visualization shows a red overlay that is darker in
proportion to how much overdraw has occurred on a pixel. Overdraw meaning that
the pixel was drawn to more than once.
- As of Dec 2019, this feature may not be working correctly.
### Image fit and download buttons.
These buttons resize the main view. they are, from left to right:
Original size - the natural size of the canvas, when it was recorded. Fit to
page - shrink enough that the whole canvas fits in the center pane. Fit to page
width - make the canvas fit horizontally but allow scrolling vertically Fit to
page height - make the canvas fit vertically but allow scrolling horizontally.
next to these is a 5th, unrelated download button which saves the current canvas
as a PNG file.
## Building and running locally
Begin by following the instructions to
[download and build Skia](/docs/user/build). Next, you'll need Skia's infrastructure repository,
which can be downloaded with
git clone https://skia.googlesource.com/buildbot
See further instructions in buildbot/debugger-app/README.md.
## Capturing SKPs
### Chromium
See https://www.chromium.org/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/
### Android
See [How to capture an SKP file from the Android framework](/docs/dev/tools/android-capture).
---
### Site Docs Dev Tools Debugvis (`site/docs/dev/tools/debugvis.md`)
---
title: "Debug Visualization"
linkTitle: "Debug Visualization"
---
Skia uses custom container types, such as `SkString` and `SkTArray<>`, which can
be inconvenient to view in a debugger.
If you frequently debug code that uses Skia types, consider installing a debug
visualizer. Skia offers debugger visualization support for the following
platforms:
- [Visual Studio and VS Code](https://skia.googlesource.com/skia/+/refs/heads/main/platform_tools/debugging/vs/Skia.natvis)
- [LLDB and Xcode](https://skia.googlesource.com/skia/+/refs/heads/main/platform_tools/debugging/lldb/skia.py)
---
### Site Docs Dev Tools Markdown (`site/docs/dev/tools/markdown.md`)
---
title: 'Markdown'
linkTitle: 'Markdown'
---
This site is build with [Hugo](https://gohugo.io/) and
[Docsy](https://www.docsy.dev/).
Any file you put under `/site/` that has the extension `.md` will be processed
as Markdown. All other files will be served directly. For example, images can be
added and they will be served correctly and referenced from within Markdown
files.
When preparing for a code review of site docs you can get a preview of how the
page will render by visiting the [Gerrit issue](https://skia-review.googlesource.com/c/skia/+/862957/####)
and clicking the eye icon to the left of the file:
See the [Docsy documentation](https://www.docsy.dev/docs/) for more details on
how to configure and use docsy. For example the
[Navigation](https://www.docsy.dev/docs/adding-content/navigation/) section
explains what frontmatter needs to be added to a page to get it to appear in the
top navigation bar.
## Frontmatter
Each page needs a frontmatter section that provides information on that page.
For example:
```
---
title: 'Markdown'
linkTitle: 'Markdown'
---
```
This is true for both Markdown and HTML pages. See
[the Docsy documentation on frontmatter](https://www.docsy.dev/docs/adding-content/content/#page-frontmatter)
for more details.
## Styling And Icons
Docsy supports both
[Bootstrap](https://getbootstrap.com/docs/5.0/getting-started/introduction/) and
[Font-Awesome](https://fontawesome.com/). Check out their documentation for what
they offer.
Bootstrap contains many classes that allow you to avoid setting styles via CSS.
For example, just using classes, we can change the font, the padding, and the
color:
```html
This is in monospace
``` Which renders as:This is in monospace
## Diagrams [Mermaid](https://mermaid-js.github.io/mermaid/#/) diagrams are enabled, so this: ````markdown ```mermaid graph TD; A-->B; A-->C; B-->D; C-->D; ``` ```` Gets rendered as: ```mermaid graph TD; A-->B; A-->C; B-->D; C-->D; ``` ## Code Snippets To get syntax highlighting in code snippets you need to specify the language, which is specified after the first code fence, for example this is how you would show HTML markup: ```` ```htmlThis is in monospace
``` ```` ## Configuration The Hugo configuration file is `config.toml` located in the site directory. --- ### Site Docs Dev Tools Sk (`site/docs/dev/tools/sk.md`) --- title: 'SK CLI Tool' linkTitle: 'SK CLI Tool' --- ## Introduction `sk` is a command-line tool which provides common functionality useful for working on Skia. ## Commands The set of supported commands will probably grow or change over time. ### asset Used for managing versioned non-code assets used by Skia developers and in CI. These are stored in [CIPD](https://chrome-infra-packages.appspot.com/p/skia/bots) and their versions are pinned under [//infra/bots/assets](https://skia.googlesource.com/skia/+/main/infra/bots/assets) in Skia. * add - Add an entry for a new asset. This does not create an initial version. * remove - Remove the entry for an existing asset. This does not remove uploaded versions. * download - Download the pinned version of the asset into the given directory. * upload - Upload a new version of the asset and update the pinned version. If a script exists to automate creation of the asset, `sk` that runs script and uploads the resulting files. Otherwise, it expects a target directory to be provided. * get-version - Print the pinned version of the asset. * set-version - Set the pinned version of the asset. `sk` verifies that the given version actually exists in CIPD. * list-versions - Print all versions of the asset which exist in CIPD. ### release-branch This automates the processes involved in creating a new release branch of Skia, including creating the Git branch itself, setting up the commit queue on the new branch (as well as retiring the commit queue for the oldest release branch), and updating the current Skia milestone. This requires administrator rights. ### try Trigger try jobs on the current active CL. Accepts zero or more job names or regular expressions. If none is provided, `try` lists all of the available try jobs and exits. ## Development The code for `sk` is located in the [Skia Infra repo](https://skia.googlesource.com/buildbot). Development in that repo follows similar practices to Skia. See [README.md](https://skia.googlesource.com/buildbot/+/main/README.md) for instructions to get started. Code for the `sk` tool itself is located under [//sk/go/](https://skia.googlesource.com/buildbot/+/main/sk/go/). Each sub-command has an associated package. ## Deployment New versions of `sk` are automatically built and uploaded to [CIPD](https://chrome-infra-packages.appspot.com/p/skia/tools/sk) as part of Skia Infra's CI/CD pipeline. The version used by Skia is pinned in [DEPS](https://skia.googlesource.com/skia/+/main/DEPS) and updated by an [autoroller](https://autoroll.skia.org/r/sk-tool-skia). --- ### Site Docs Dev Tools Tracing (`site/docs/dev/tools/tracing.md`) --- title: "Tracing Skia Execution" linkTitle: "Tracing Skia Execution" --- Introduction ------------ Skia is instrumented to provide execution traces in several ways. Within Chrome, Skia is traced with the standard [tracing interface](chrome://tracing), along with the rest of Chromium. In the Android framework, Skia's tracing is integrated into [atrace](https://source.android.com/devices/tech/debug/ftrace). For standalone builds, Skia's tools (DM, nanobench, and Viewer) are capable of tracing execution in three ways, controlled by the `--trace` command line argument. Standalone Tracing ------------------ Most arguments to `--trace` will be interpreted as a filename (the two exceptions are described below), and trace events will be written to that file in JSON format, suitable for viewing with [chrome://tracing](chrome://tracing). # Run DM on several GMs to get tracing data out/Release/dm --config gl --match bleed --trace gl_bleed_gms.json This creates a file `gl_bleed_gms.json` in the current directory. There are limitations in Chrome's tracing tool that prevent loading a file larger than 256 MB. To stay under that limit (and avoid clutter and slowdown in the interface), it's best to run a small number of tests/benchmarks when tracing. Once you have generated a file in this way, go to [chrome://tracing](chrome://tracing), click Load: ... then select the JSON file. The data will be loaded and can be navigated/inspected using the tracing tools. Tip: press '?' for a help screen explaining the available keyboard and mouse controls. Android ATrace -------------- Running any tool with `--trace atrace` on an Android device will cause the application to forward tracing information to [atrace](https://source.android.com/devices/tech/debug/ftrace). On other platforms, this has no effect. If you run `systrace` from the host command line, you will need to supply `-a| Effect | text | images | everything else |
|---|---|---|---|
| SkMaskFilter | drop | ignore | ignore |
| SkPathEffect | ignore | n/a | expand |
| SkColorFilter | ignore | expand | ignore |
| SkImageFilter | expand | expand | expand |
| unsupported SkXferModes | ignore | ignore | ignore |
| non-gradient SkShader | expand | n/a | expand |