aboutsummaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
Diffstat
-rw-r--r--AUTHORS1
-rw-r--r--site/dev/chrome/commandbuffer.md8
-rw-r--r--site/dev/chrome/multi_repo_trybots.md6
-rw-r--r--site/dev/chrome/repo.md6
-rw-r--r--site/dev/contrib/flatten.md18
-rw-r--r--site/dev/contrib/patch.md25
-rw-r--r--site/dev/contrib/simd.md18
-rw-r--r--site/dev/contrib/style.md43
-rw-r--r--site/dev/contrib/submit.md20
-rw-r--r--site/dev/design/conical/index.md18
-rw-r--r--site/dev/testing/automated_testing.md14
-rw-r--r--site/dev/testing/fonts.md4
-rw-r--r--site/dev/testing/ios.md3
-rw-r--r--site/dev/testing/skiaperf.md2
-rw-r--r--site/dev/testing/testing.md39
-rw-r--r--site/dev/tools/markdown.md29
-rw-r--r--site/user/build.md2
-rw-r--r--site/user/download.md14
-rw-r--r--site/user/quick/METADATA2
-rw-r--r--site/user/quick/index.md5
-rw-r--r--site/user/sample/color.md14
-rw-r--r--site/user/sample/pdf.md2
-rw-r--r--site/user/tips.md18
23 files changed, 162 insertions, 149 deletions
diff --git a/AUTHORS b/AUTHORS
index 6def302e3e..6ebbda8e1a 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -15,6 +15,7 @@ ACCESS CO., LTD. <*@access-company.com>
Anthony Catel <paraboul@gmail.com>
ARM <*@arm.com>
Ehsan Akhgari <ehsan.akhgari@gmail.com>
+Facebook, Inc. <*fb.com>
George Wright <george@mozilla.com>
GiWan Go <gogil@stealien.com>
Google Inc. <*@google.com>
diff --git a/site/dev/chrome/commandbuffer.md b/site/dev/chrome/commandbuffer.md
index 2afa5c9194..b14a1e96ec 100644
--- a/site/dev/chrome/commandbuffer.md
+++ b/site/dev/chrome/commandbuffer.md
@@ -10,13 +10,13 @@ the command buffer as a shared library and thus no GYP/GN flags are
required.
The command buffer standalone shared library is built in a Chromium checkout
-by building the 'command_buffer_gles2' target. The command buffer should be
-built with the is_component_build in GN set to false. This will produce a .so,
+by building the `command_buffer_gles2` target. The command buffer should be
+built with the `is_component_build` in GN set to false. This will produce a .so,
.dylib, or .dll depending on the target OS. This should be copied alongside
the dm or nanobench executable built from a Skia repository.
-Both tools have a 'commandbuffer' config which can be used with the --config
+Both tools have a `commandbuffer` config which can be used with the `--config`
option to the tool and will run the tests or benchmarks using the command buffer
library. Unit tests in dm always run on all appropriate and available backends
-regardless of the --config flag.
+regardless of the `--config` flag.
diff --git a/site/dev/chrome/multi_repo_trybots.md b/site/dev/chrome/multi_repo_trybots.md
index 4c6f09da45..34a8d96f12 100644
--- a/site/dev/chrome/multi_repo_trybots.md
+++ b/site/dev/chrome/multi_repo_trybots.md
@@ -67,7 +67,7 @@ possible to patch the files manually by adding the following to
},
Then, copy all 'out of tree' files into \<chromium>/src/patch/, using the same
-directory structure used by Chromium. When 'gclient runhooks' is run, the files
+directory structure used by Chromium. When `gclient runhooks` is run, the files
in \<chromium>/src/patch/ will be copied to and overwrite corresponding files in
\<chromium>/src/. For example, if changing \<skia>/include/core/SkPath.h, place
a copy of the modified SkPath.h at
@@ -80,5 +80,5 @@ https://crrev.com/1866773002/#ps20001 .
Try the patch
-------------
After committing a \<chromium>/src/DEPS or \<chromium>/src/patch/ change
-locally, 'git cl upload' can be used in the usual way. Be sure to add
-'COMMIT=false' to the issue description to avoid accidentally checking it in.
+locally, `git cl upload` can be used in the usual way. Be sure to add
+`COMMIT=false` to the issue description to avoid accidentally checking it in.
diff --git a/site/dev/chrome/repo.md b/site/dev/chrome/repo.md
index 545f154a2a..eaa658571a 100644
--- a/site/dev/chrome/repo.md
+++ b/site/dev/chrome/repo.md
@@ -6,9 +6,9 @@ To work on Skia inside a Chromium checkout, run the following:
cd chromium/src/third_party/skia
python tools/git-sync-deps
-This command does a minimal "just sync the DEPS" emulation of gclient sync for
-Skia into chromium/src/third_party/skia/third_party. After that, make dm or
-./gyp_skia && ninja -C out/Debug dm in chromium/src/third_party/skia will get
+This command does a minimal "just sync the DEPS" emulation of `gclient sync` for
+Skia into chromium/src/third_party/skia/third_party. After that, `make dm` or
+`./gyp_skia && ninja -C out/Debug dm` in chromium/src/third_party/skia will get
you rolling.
We no longer recommend the .gclient file manipulation to have Chromium DEPS also
diff --git a/site/dev/contrib/flatten.md b/site/dev/contrib/flatten.md
index 192571e1c7..0b3663f560 100644
--- a/site/dev/contrib/flatten.md
+++ b/site/dev/contrib/flatten.md
@@ -1,13 +1,13 @@
Flattenables
============
-Many objects in Skia, such as SkShaders and other effects on SkPaint, need to be
+Many objects in Skia, such as `SkShaders` and other effects on `SkPaint`, need to be
flattened into a data stream for either transport or as part of the key to the
-font cache. Classes for these objects should derive from SkFlattenable or one of
+font cache. Classes for these objects should derive from `SkFlattenable` or one of
its subclasses. If you create a new flattenable class, you need to make sure you
do a few things so that it will work on all platforms:
-1: Override the method flatten (the default scope is protected):
+1: Override the method `flatten` (the default scope is protected):
<!--?prettify?-->
~~~~
@@ -18,7 +18,7 @@ virtual void flatten(SkFlattenableWriteBuffer& buffer) const override {
~~~~
2: Override the (protected) constructor that creates an object from an
-SkFlattenableReadBuffer:
+`SkFlattenableReadBuffer`:
<!--?prettify?-->
~~~~
@@ -39,10 +39,10 @@ public:
SK_DECLARE_PUBLIC_FLATTENABLE_DESERIALIZATION_PROCS(SkNewClass)
~~~~
-4: If your class is declared in a .cpp file or in a private header file, create a
+4: If your class is declared in a `.cpp` file or in a private header file, create a
function to register its group:
This occurs in cases where the classes are hidden behind a factory, like many effects
-and shaders are. Then in the parent class header file (such as SkGradientShader) you
+and shaders are. Then in the parent class header file (such as `SkGradientShader`) you
need to add:
<!--?prettify?-->
@@ -69,9 +69,9 @@ SK_DEFINE_FLATTENABLE_REGISTRAR_GROUP_END
5: Register your flattenable with the global registrar:
-You need to add one line to SkFlattenable::InitalizeFlattenables(). To register the
-flattenable in a Skia build, that function is defined in SkGlobalInitialization_default.cpp.
-For Chromium, it is in SkGlobalInitialization_chromium.cpp.
+You need to add one line to `SkFlattenable::InitalizeFlattenables()`. To register the
+flattenable in a Skia build, that function is defined in `SkGlobalInitialization_default.cpp`.
+For Chromium, it is in `SkGlobalInitialization_chromium.cpp`.
For a single flattenable add
<!--?prettify?-->
diff --git a/site/dev/contrib/patch.md b/site/dev/contrib/patch.md
index cf8b35bdeb..b7b29f06fd 100644
--- a/site/dev/contrib/patch.md
+++ b/site/dev/contrib/patch.md
@@ -7,30 +7,31 @@ other situations too, like if you just want to try out somebody else's patch
locally.)
Notes:
+
* For the examples below, we will assume that this is the change you want
to patch into your local checkout: https://codereview.appspot.com/6201055/
* These instructions should work on Mac or Linux; Windows is trickier,
because there is no standard Windows "patch" tool.
-See also:
-http://dev.chromium.org/developers/contributing-code#TOC-Instructions-for-Reviewer:-Checking-in-the-patch-for-a-non-committer
+See also [Contributing Code for The Chromium Projects]
+(http://dev.chromium.org/developers/contributing-code#TOC-Instructions-for-Reviewer:-Checking-in-the-patch-for-a-non-committer).
-If you use git cl, then you should be able to use the shortcut:
+If you use `git cl`, then you should be able to use the shortcut:
~~~~
git cl patch 6201055
~~~~
-If you use gcl, or the above doesn't work, the following should always work.
+If you use `gcl`, or the above doesn't work, the following should always work.
1. Prepare your local workspace to accept the patch.
- * cd into the root directory (usually trunk/) of the workspace where you
+ * cd into the root directory (usually `trunk/`) of the workspace where you
want to apply the patch.
* Make sure that the workspace is up-to-date and clean (or "updated and
clean enough" for your purposes). If the codereview patch was against
an old revision of the repo, you may need to sync your local workspace
- to that same revision...
+ to that same revision.
2. Download the raw patch set.
@@ -50,7 +51,7 @@ If you use gcl, or the above doesn't work, the following should always work.
~~~~
* Otherwise, figure out some other way to download this file and save it as
- 'patch.txt'
+ `patch.txt`
3. Apply this patch to your local checkout.
@@ -61,12 +62,12 @@ If you use gcl, or the above doesn't work, the following should always work.
patch -p1 <patch.txt
~~~~
- * Then you can run diff and visually check the local changes.
+ * Then you can run `diff` and visually check the local changes.
4. Complications: If the patch fails to apply, the following may be happening:
- Wrong revision. Maybe your local workspace is not up to date? Or maybe the
- patch was made against an old revision of the repository, and cannot be applied
- to the latest revision? (In that case, revert any changes and sync your
- workspace to an older revision, then re-apply the patch.)
+ * Wrong revision. Maybe your local workspace is not up to date? Or maybe the
+ patch was made against an old revision of the repository, and cannot be applied
+ to the latest revision? (In that case, revert any changes and sync your
+ workspace to an older revision, then re-apply the patch.)
diff --git a/site/dev/contrib/simd.md b/site/dev/contrib/simd.md
index e2e63107d2..6ec29c525a 100644
--- a/site/dev/contrib/simd.md
+++ b/site/dev/contrib/simd.md
@@ -32,7 +32,7 @@ This temptation starts to break down when you notice:
- math written with either SSE or NEON instrinsics is still very hard to read; and
- sometimes we want to work with 4 floats, but sometimes 2, maybe even 8, etc.
-So we use a wrapper class `SkNf<N>`, parameterized on N, how many floats the vector contains, constrained at compile time to be a power of 2. `SkNf` provides all the methods you'd expect on vector of N floats: loading and storing from float arrays, all the usual arithmetic operators, min and max, low and high precision reciprocal and sqrt, all the usual comparison operators, and a `.thenElse()` method acting as a non-branching ternary `?:` operator. To support Skia's main graphic needs, `SkNf` can also load and store from a vector of N _bytes_, converting up to a float when loading and rounding down to [0,255] when storing.
+So we use a wrapper class `SkNf<N>`, parameterized on N, how many floats the vector contains, constrained at compile time to be a power of 2. `SkNf` provides all the methods you'd expect on a vector of N floats: loading and storing from float arrays, all the usual arithmetic operators, min and max, low and high precision reciprocal and sqrt, all the usual comparison operators, and a `.thenElse()` method acting as a non-branching ternary `?:` operator. To support Skia's main graphic needs, `SkNf` can also load and store from a vector of N _bytes_, converting up to a float when loading and rounding down to [0,255] when storing.
As a convenience, `SkNf<N>` has two default implementations: `SkNf<1>` performs all these operations on a single float, and the generic `SkNf<N>` simply recurses onto two `SkNf<N/2>`. This allows our different backends to inject specialiations where most natural: the portable backend does nothing, so all `SkNf<N>` recurse down to the default `SkNf<1>`; the NEON backend specializes `SkNf<2>` with `float32x2_t` and 64-bit SIMD methods, and `SkNf<4>` with `float32x4_t` and 128-bit SIMD methods; the SSE backend specializes both `SkNf<4>` and `SkNf<2>` to use the full or lower half of an `__m128` vector, respectively. A future AVX backend could simply drop in an `SkNf<8>` specialization.
@@ -41,16 +41,16 @@ Our most common float use cases are working with 2D coordinates and with 4-float
`SkNf` in practice
----------------
-To date we have implemented several parts of Skia using Sk4f:
+To date we have implemented several parts of Skia using `Sk4f`:
1. `SkColorMatrixFilter`
2. `SkRadialGradient`
3. `SkColorCubeFilter`
4. Three complicated `SkXfermode` subclasses: `ColorBurn`, `ColorDodge`, and `SoftLight`.
-In all these cases, we have been able to write a single implementation, producing the same results cross-platform. The first three of those sites using Sk4f are entirely newly vectorized, and run much faster than the previous portable implementations. The 3 Sk4f transfermodes replaced portable, SSE, and NEON implementations which all produced different results, and the Sk4f versions are all faster than their predecessors.
+In all these cases, we have been able to write a single implementation, producing the same results cross-platform. The first three of those sites using `Sk4f` are entirely newly vectorized, and run much faster than the previous portable implementations. The 3 `Sk4f` transfermodes replaced portable, SSE, and NEON implementations which all produced different results, and the `Sk4f` versions are all faster than their predecessors.
-`SkColorCubeFilter` stands out as a particularly good example of how and why to use Sk4f over custom platform-specific intrinsics. Starting from some portable code and a rather slow SSE-only sketch, a Google Chromium dev, an Intel contributor, and I worked together to write an Sk4f version that's more than twice as fast as the original, and runs fast on _both_ x86 and ARM.
+`SkColorCubeFilter` stands out as a particularly good example of how and why to use `Sk4f` over custom platform-specific intrinsics. Starting from some portable code and a rather slow SSE-only sketch, a Google Chromium dev, an Intel contributor, and I worked together to write an `Sk4f` version that's more than twice as fast as the original, and runs fast on _both_ x86 and ARM.
`SkPx` for 8- and 16-bit fixed point math
----------------------------------------
@@ -96,7 +96,7 @@ Building an abstraction layer over 8- and 16-bit fixed point math has proven to
// A faster approximation of (SkPx * Alpha).div255().
SkPx.approxMulDiv255(Alpha) -> SkPx
-We allow each `SkPx` backend to choose how it physically represents `SkPx`, `SkPx::Wide`, and `SkPx::Alpha` and to choose any power of two as its `SkPx::N` sweet spot. Code working with SkPx typically runs a loop like this:
+We allow each `SkPx` backend to choose how it physically represents `SkPx`, `SkPx::Wide`, and `SkPx::Alpha` and to choose any power of two as its `SkPx::N` sweet spot. Code working with `SkPx` typically runs a loop like this:
while (n >= SkPx::N) {
// Apply some_function() to SkPx::N pixels.
@@ -112,7 +112,7 @@ The portable code is of course the simplest place to start looking at implementa
The most important difference between SSE and NEON when working in fixed point is that SSE works most naturally with 4 interlaced pixels at a time (argbargbargbargb), while NEON works most naturally with 8 planar pixels at a time (aaaaaaaa, rrrrrrrr, gggggggg, bbbbbbbb). Trying to jam one of these instruction sets into the other's idiom ends up somewhere between not quite optimal (working with interlaced pixels in NEON) and ridiculously inefficient (trying to work with planar pixels in SSE).
-So `SkPx`'s SSE backend sets N to 4 pixels, stores them interlaced in an `__m128i`, representing `Wide` as two `__m128i` and `Alpha` as an `__m128i` with each pixel's alpha component replicated four times. SkPx's NEON backend works with 8 planar pixels, loading them with `vld4_u8` into an `uint8x8x4_t` struct of 4 8-component `uint8x8_t` planes. `Alpha` is just a single `uint8x8_t` 8-component plane, and `Wide` is NEON's natural choice, `uint16x8x4_t`.
+So `SkPx`'s SSE backend sets N to 4 pixels, stores them interlaced in an `__m128i`, representing `Wide` as two `__m128i` and `Alpha` as an `__m128i` with each pixel's alpha component replicated four times. `SkPx`'s NEON backend works with 8 planar pixels, loading them with `vld4_u8` into an `uint8x8x4_t` struct of 4 8-component `uint8x8_t` planes. `Alpha` is just a single `uint8x8_t` 8-component plane, and `Wide` is NEON's natural choice, `uint16x8x4_t`.
(It's fun to speculate what an AVX2 backend might look like. Do we make `SkPx` declare it wants to work with 8 pixels at a time, or leave it at 4? Does `SkPx` become `__m256i`, or maybe only `SkPx::Wide` does? What's the best way to represent `Alpha`? And of course, what about AVX-512?)
@@ -126,8 +126,8 @@ These details will inevitably change over time. The important takeaway here is,
I am in the process of rolling out `SkPx`. Some Skia code is already using its precursor, `Sk4px`, which is a bit like `SkPx` that forces `N=4` and restricts the layout to always use interlaced pixels: i.e. fine for SSE, not great for NEON.
1. All ~20 other `SkXfermode` subclasses that are not implemented with `SkNf`.
- 2. SkBlitRow::Color32
- 3. SkBlitMask::BlitColor
+ 2. `SkBlitRow::Color32`
+ 3. `SkBlitMask::BlitColor`
I can certainly say that the `Sk4px` and `SkPx` implementations of these methods are clearer, less buggy, and that all the `SkXfermode` implementations sped up at least 2x when porting from custom per-platform intrinsics. `Sk4px` has lead to some pretty bad performance regressions that `SkPx` is designed to avoid. This is an area of active experiementation and iteration.
@@ -138,4 +138,4 @@ I am confident that Skia developers soon will be able to write single, clear, ma
I'm also confident that if you're looking to use floats, `SkNf` is ready. Do not write NEON or SSE SIMD code if you're looking to use floats, and do not accept external contributions that do so. Use `SkNf` instead.
-`SkPx` is less proven, and while its design and early tests look promising, it's still at the stage where we should try it aware that we might need to fall back on hand-written SSE or NEON. \ No newline at end of file
+`SkPx` is less proven, and while its design and early tests look promising, it's still at the stage where we should try it aware that we might need to fall back on hand-written SSE or NEON.
diff --git a/site/dev/contrib/style.md b/site/dev/contrib/style.md
index 17989b3c82..6a8c604af5 100644
--- a/site/dev/contrib/style.md
+++ b/site/dev/contrib/style.md
@@ -81,7 +81,7 @@ int herdCats(const Array& cats) {
Enum values are prefixed with k. Unscoped enum values are post fixed with
an underscore and singular name of the enum name. The enum itself should be
singular for exclusive values or plural for a bitfield. If a count is needed it
-is k&lt;singular enum name&gt;Count and not be a member of the enum (see example):
+is `k<singular enum name>Count` and not be a member of the enum (see example):
<!--?prettify?-->
~~~~
@@ -167,8 +167,8 @@ Ganesh macros that are GL-specific should be prefixed GR_GL.
#define GR_GL_TEXTURE0 0xdeadbeef
~~~~
-Ganesh prefers that macros are always defined and the use of #if MACRO rather than
-#ifdef MACRO.
+Ganesh prefers that macros are always defined and the use of `#if MACRO` rather than
+`#ifdef MACRO`.
<!--?prettify?-->
~~~~
@@ -179,14 +179,14 @@ Ganesh prefers that macros are always defined and the use of #if MACRO rather th
#endif
~~~~
-Skia tends to use #ifdef SK_MACRO for boolean flags.
+Skia tends to use `#ifdef SK_MACRO` for boolean flags.
Braces
------
-Open braces don't get a newline. “else” and “else if” appear on same line as
+Open braces don't get a newline. `else` and `else if` appear on same line as
opening and closing braces unless preprocessor conditional compilation
-interferes. Braces are always used with if, else, while, for, and do.
+interferes. Braces are always used with `if`, `else`, `while`, `for`, and `do`.
<!--?prettify?-->
~~~~
@@ -296,8 +296,8 @@ Classes
-------
Unless there is a need for forward declaring something, class declarations
-should be ordered public, protected, private. Each should be preceded by a
-newline. Within each visibility section (public, private), fields should not be
+should be ordered `public`, `protected`, `private`. Each should be preceded by a
+newline. Within each visibility section (`public`, `private`), fields should not be
intermixed with methods.
<!--?prettify?-->
@@ -410,6 +410,7 @@ if (count > 0) {
~~~~
Comments
+--------
We use doxygen-style comments.
@@ -435,16 +436,16 @@ We follow the Google C++ guide for ints and are slowly making older code conform
(http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Integer_Types)
-Summary: Use int unless you have need a guarantee on the bit count, then use
-stdint.h types (int32_t, etc). Assert that counts, etc are not negative instead
-of using unsigned. Bitfields use uint32_t unless they have to be made shorter
+Summary: Use `int` unless you have need a guarantee on the bit count, then use
+`stdint.h` types (`int32_t`, etc). Assert that counts, etc are not negative instead
+of using unsigned. Bitfields use `uint32_t` unless they have to be made shorter
for packing or performance reasons.
-nullptr, 0
+`nullptr`, 0
-------
-Use nullptr for pointers, 0 for ints. We prefer explicit nullptr comparisons when
-checking for nullptr pointers (as documentation):
+Use `nullptr` for pointers, 0 for ints. We prefer explicit `nullptr` comparisons when
+checking for `nullptr` pointers (as documentation):
<!--?prettify?-->
~~~~
@@ -453,7 +454,7 @@ if (nullptr == x) { // slightly preferred over if (!x)
}
~~~~
-When checking non-nullptr pointers explicit comparisons are not required because it
+When checking non-`nullptr` pointers explicit comparisons are not required because it
reads like a double negative:
<!--?prettify?-->
@@ -485,8 +486,8 @@ modify_foo(&foo);
~~~~
This way, if return value optimization cannot be used there is no performance
-hit. It also means that modify_foo can actually return a boolean for whether the
-call was successful. In this case, initialization of foo can potentially be
+hit. It also means that `modify_foo` can actually return a boolean for whether the
+call was successful. In this case, initialization of `foo` can potentially be
skipped on failure (assuming the constructor for SkFoo does no initialization).
<!--?prettify?-->
@@ -504,7 +505,7 @@ bool modify_foo(SkFoo* foo) {
Function Parameters
-------------------
-Mandatory constant object parameters are passed to functions as const references
+Mandatory constant object parameters are passed to functions as `const` references
if they are not retained by the receiving function. Optional constant object
parameters are passed to functions as const pointers. Objects that the called
function will retain, either directly or indirectly, are passed as pointers.
@@ -521,8 +522,8 @@ SkScalar SkPaint::getFontMetrics(FontMetric* metrics, SkScalar scale) const;
void SkContainer::insert(const SkFoo* foo);
~~~~
-If function arguments or parameters do not all fit on one line, they may be
-lined up with the first parameter on the same line
+If function arguments or parameters do not all fit on one line, the overflowing
+parameters may be lined up with the first parameter on the next line
<!--?prettify?-->
~~~~
@@ -533,7 +534,7 @@ void drawBitmapRect(const SkBitmap& bitmap, const SkRect& dst,
}
~~~~
-or placed on the next line indented eight spaces
+or all parameters placed on the next line and indented eight spaces
<!--?prettify?-->
~~~~
diff --git a/site/dev/contrib/submit.md b/site/dev/contrib/submit.md
index 4dd380d77a..1d36e1f9d7 100644
--- a/site/dev/contrib/submit.md
+++ b/site/dev/contrib/submit.md
@@ -65,9 +65,9 @@ name and contact info to the AUTHORS file as a part of your CL.
Now that you've made a change and written a test for it, it's ready for the code
review! Submit a patch and getting it reviewed is fairly easy with depot tools.
-Use git-cl, which comes with [depot
+Use `git-cl`, which comes with [depot
tools](http://sites.google.com/a/chromium.org/dev/developers/how-tos/install-depot-tools).
-For help, run git-cl help.
+For help, run `git cl help`.
### Find a reviewer
@@ -78,7 +78,7 @@ has been editing it.
### 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:
+Use `git cl` to upload your change:
<!--?prettify lang=sh?-->
@@ -99,11 +99,11 @@ 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.
+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.
+or using bin/try, a small wrapper for `git cl try` which helps to choose try jobs.
From a Skia checkout:
bin/try --list
@@ -125,7 +125,7 @@ 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.
+send the email directly when uploading a change using `git-cl`.
The review process
@@ -155,8 +155,8 @@ code, commit it again locally, and then run git cl upload again e.g.
git cl upload
Once you're ready for another review, use **Reply** again to send another
-notification (it is helpful to tell the review what you did with respect to each
-of their comments). When the reviewer is happy with your patch, they will
+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
@@ -176,7 +176,7 @@ 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
+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.
@@ -219,7 +219,7 @@ adjustments at his/her discretion). If so, you can mark your change as
* 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` will squash all your commits into a single one with the description you used when you uploaded your change.
~~~~
git cl land
diff --git a/site/dev/design/conical/index.md b/site/dev/design/conical/index.md
index 0ad733e786..2efb90c9ba 100644
--- a/site/dev/design/conical/index.md
+++ b/site/dev/design/conical/index.md
@@ -14,21 +14,21 @@ MathJax.Hub.Config({
(Please refresh the page if you see a lot of dollars instead of math symbols.)
We present a fast shading algorithm (compared to bruteforcely solving the quadratic equation of
-gradient $t$) for computing the two-point conical gradient (i.e., createRadialGradient in
+gradient $t$) for computing the two-point conical gradient (i.e., `createRadialGradient` in
[spec](https://html.spec.whatwg.org/multipage/canvas.html#dom-context-2d-createradialgradient)).
-It reduced the number of multiplications per pixel from ~10 downto 3, and brought a speedup up to
+It reduced the number of multiplications per pixel from ~10 down to 3, and brought a speedup of up to
26% in our nanobenches.
This document has 3 parts:
-1. Problem Statement and Setup
-2. Algorithm
-3. Appendix
+1. [Problem Statement and Setup](#problem-statement)
+2. [Algorithm](#algorithm)
+3. [Appendix](#appendix)
Part 1 and 2 are self-explanatory. Part 3 shows how to geometrically proves our Theorem 1 in part
2; it's more complicated but it gives us a nice picture about what's going on.
-## Problem Statement and Setup
+## <span id="problem-statement">Problem Statement and Setup</span>
Let two circles be $C_0, r_0$ and $C_1, r_1$ where $C$ is the center and $r$ is the radius. For any
point $P = (x, y)$ we want the shader to quickly compute a gradient $t \in \mathbb R$ such that $p$
@@ -65,9 +65,9 @@ transformation to map $C_f, C_1$ to $(0, 0), (1, 0)$. After the transformation:
From now on, we'll focus on how to quickly computes $x_t$. Note that $r_t > 0$ so we're only
interested positive solution $x_t$. Again, if there are multiple $x_t$ solutions, we may want to
find the bigger one if $1 - f > 0$, and smaller one if $1 - f < 0$, so the corresponding $t$ is
-always the bigger one (note that $f \neq 1$, otherwise we'll swap $c_0, r_0$ with $c_1, r_1$).
+always the bigger one (note that $f \neq 1$, otherwise we'll swap $C_0, r_0$ with $C_1, r_1$).
-## Algorithm
+## <span id="algorithm">Algorithm</span>
**Theorem 1.** The solution to $x_t$ is
@@ -161,7 +161,7 @@ if it saves the $0.5 \cdot (1/a), 4a, r_0^2$ and $(r_1 - r_0) r_0$ multiplicatio
6 multiplications. Moreover, it sends in 4 unitofmrs to the shader while our algorithm only needs 2
uniforms ($1/r_1$ and $f$).
-## Appendix
+## <span id="appendix">Appendix</span>
**Lemma 1.** Draw a ray from $C_f = (0, 0)$ to $P = (x, y)$. For every
intersection points $P_1$ between that ray and circle $C_1 = (1, 0), r_1$, there exists an $x_t$
diff --git a/site/dev/testing/automated_testing.md b/site/dev/testing/automated_testing.md
index 8fb64cc8ad..ecdd484e73 100644
--- a/site/dev/testing/automated_testing.md
+++ b/site/dev/testing/automated_testing.md
@@ -20,18 +20,18 @@ may automatically retry tasks within its set limits. Jobs are not retried.
Multiple jobs may share the same task, for example, tests on two different
Android devices which use the same compiled code.
-Each Skia repository has an infra/bots/tasks.json file which defines the jobs
+Each Skia repository has an `infra/bots/tasks.json` file which defines the jobs
and tasks for the repo. Most jobs will run at every commit, but it is possible
to specify nightly and weekly jobs as well. For convenience, most repos also
-have a gen_tasks.go which will generate tasks.json. You will need to
+have a `gen_tasks.go` which will generate `tasks.json`. You will need to
[install Go](https://golang.org/doc/install). From the repository root:
$ go get -u go.skia.org/infra/...
$ go run infra/bots/gen_tasks.go
-It is necessary to run gen_tasks.go every time it is changed or every time an
+It is necessary to run `gen_tasks.go` every time it is changed or every time an
[asset](https://skia.googlesource.com/skia/+/master/infra/bots/assets/README.md)
-has changed. There is also a test mode which simply verifies that the tasks.json
+has changed. There is also a test mode which simply verifies that the `tasks.json`
file is up to date:
$ go run infra/bots/gen_tasks.go --test
@@ -44,12 +44,12 @@ 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.
+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.
+or using `bin/try`, a small wrapper for `git cl try` which helps to choose try jobs.
From a Skia checkout:
bin/try --list
diff --git a/site/dev/testing/fonts.md b/site/dev/testing/fonts.md
index 15e7727041..cb2a9e57ee 100644
--- a/site/dev/testing/fonts.md
+++ b/site/dev/testing/fonts.md
@@ -29,6 +29,6 @@ SkTypeface* typeface = sk_tool_utils::create_portable_typeface(const char* name,
SkFontStyle style);
~~~~
-Eventually, both 'set_portable_typeface()' and 'create_portable_typeface()' will be
-removed. Instead, a test-wide 'SkFontMgr' will be selected to choose portable
+Eventually, both `set_portable_typeface()` and `create_portable_typeface()` will be
+removed. Instead, a test-wide `SkFontMgr` will be selected to choose portable
fonts or resource fonts.
diff --git a/site/dev/testing/ios.md b/site/dev/testing/ios.md
index e6535e17ea..5ae5368fc6 100644
--- a/site/dev/testing/ios.md
+++ b/site/dev/testing/ios.md
@@ -24,6 +24,7 @@ Follow these steps to install them:
(Note: All these are part of the *libimobiledevice* project but packaged/developed
under different names. The *cask* extension to *brew* is necessary to install
*osxfuse* and *ifuse*, which allows to mount the application directory on an iOS device).
+
```
brew install libimobiledevice
brew install ideviceinstaller
@@ -31,7 +32,9 @@ brew install caskroom/cask/brew-cask
brew install Caskroom/cask/osxfuse
brew install ifuse
```
+
* Install node.js and ios-deploy
+
```
$ brew update
$ brew install node
diff --git a/site/dev/testing/skiaperf.md b/site/dev/testing/skiaperf.md
index 921df2e987..005b30b044 100644
--- a/site/dev/testing/skiaperf.md
+++ b/site/dev/testing/skiaperf.md
@@ -8,7 +8,7 @@ infrastructure.
<img src=Perf.png style="margin-left:30px" align="left" width="800"/> <br clear="left">
Skia tests across a large number of platforms and configurations, and each
-commit to Skia generates 240,000 individual values are sent to Perf,
+commit to Skia generates 240,000 individual values that are sent to Perf,
consisting mostly of performance benchmark results, but also including memory
and coverage data.
diff --git a/site/dev/testing/testing.md b/site/dev/testing/testing.md
index d58abfb400..6129550061 100644
--- a/site/dev/testing/testing.md
+++ b/site/dev/testing/testing.md
@@ -82,30 +82,31 @@ stand alone. A couple thousand tasks is pretty normal. Let's look at the
status line for one of those tasks.
~~~
( 25MB 1857) 1.36ms 8888 image mandrill_132x132_12x12.astc-5-subsets
+ [1] [2] [3] [4]
~~~
This status line tells us several things.
-First, it tells us that at the time we wrote the status line, the maximum
-amount of memory DM had ever used was 25MB. Note this is a high water mark,
-not the current memory usage. This is mostly useful for us to track on our
-buildbots, some of which run perilously close to the system memory limit.
+ 1. The maximum amount of memory DM had ever used was 25MB. Note this is a
+ high water mark, not the current memory usage. This is mostly useful for us
+ to track on our buildbots, some of which run perilously close to the system
+ memory limit.
-Next, the status line tells us that there are 1857 unfinished tasks, either
-currently running or waiting to run. We generally run one task per hardware
-thread available, so on a typical laptop there are probably 4 or 8 running at
-once. Sometimes the counts appear to show up out of order, particularly at DM
-startup; it's harmless, and doesn't affect the correctness of the run.
+ 2. The number of unfinished tasks, in this example there are 1857, either
+ currently running or waiting to run. We generally run one task per hardware
+ thread available, so on a typical laptop there are probably 4 or 8 running at
+ once. Sometimes the counts appear to show up out of order, particularly at DM
+ startup; it's harmless, and doesn't affect the correctness of the run.
-Next, we see this task took 1.36 milliseconds to run. Generally, the precision
-of this timer is around 1 microsecond. The time is purely there for
-informational purposes, to make it easier for us to find slow tests.
+ 3. Next, we see this task took 1.36 milliseconds to run. Generally, the
+ precision of this timer is around 1 microsecond. The time is purely there for
+ informational purposes, to make it easier for us to find slow tests.
-Finally we see the configuration and name of the test we ran. We drew the test
-"mandrill_132x132_12x12.astc-5-subsets", which is an "image" source, into an
-"8888" sink.
+ 4. The configuration and name of the test we ran. We drew the test
+ "mandrill_132x132_12x12.astc-5-subsets", which is an "image" source, into an
+ "8888" sink.
-When DM finishes running, you should find a directory with file named dm.json,
+When DM finishes running, you should find a directory with file named `dm.json`,
and some nested directories filled with lots of images.
~~~
$ ls dm_output
@@ -127,9 +128,9 @@ dm_output/8888/gm/bezier_quad_effects.png
The directories are nested first by sink type (`--config`), then by source type (`--src`).
The image from the task we just looked at, "8888 image mandrill_132x132_12x12.astc-5-subsets",
-can be found at dm_output/8888/image/mandrill_132x132_12x12.astc-5-subsets.png.
+can be found at `dm_output/8888/image/mandrill_132x132_12x12.astc-5-subsets.png`.
-dm.json is used by our automated testing system, so you can ignore it if you
+`dm.json` is used by our automated testing system, so you can ignore it if you
like. It contains a listing of each test run and a checksum of the image
generated for that run.
@@ -142,7 +143,7 @@ the same exact .png, but have their checksums differ.
Unit tests don't generally output anything but a status update when they pass.
If a test fails, DM will print out its assertion failures, both at the time
they happen and then again all together after everything is done running.
-These failures are also included in the dm.json file.
+These failures are also included in the `dm.json` file.
DM has a simple facility to compare against the results of a previous run:
diff --git a/site/dev/tools/markdown.md b/site/dev/tools/markdown.md
index 8f1198a074..fb49339fa9 100644
--- a/site/dev/tools/markdown.md
+++ b/site/dev/tools/markdown.md
@@ -1,11 +1,11 @@
Markdown
========
-This site can handle normal MarkDown and many common extensions. To learn
+This site can handle normal Markdown and many common extensions. To learn
how the following is done please see the [source for this page](./markdown.md).
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.
+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 skia.org site and add a query parameter `cl`
@@ -62,7 +62,7 @@ to appear after the members of `dirOrder` or `fileOrder` respectively. All
files and directories that aren't controlled by a METADATA file are sorted in
alphabetical order by their filename.
-Some Example MarkDown
+Some Example Markdown
---------------------
This is a [link](https://www.google.com). You can also create
@@ -136,7 +136,7 @@ such as 1/2 are rendered nicely.
> ###### Deep
And you can <b>always</b> use HTML, which is useful for features that can't be
-done in MarkDown, such as iframes, but try to avoid using HTML outside of
+done in Markdown, such as iframes, but try to avoid using HTML outside of
sitations like that.
<svg viewBox="0 0 24 24" height="24px" width="24px" style="display: inline;">
<g>
@@ -150,14 +150,14 @@ sitations like that.
Reference
=========
-Below is a longer reference on the MarkDown that docserver accepts.
+Below is a longer reference on the Markdown that docserver accepts.
Paragraphs
----------
A paragraph is simply one or more consecutive lines of text, separated
by one or more blank lines. (A blank line is any line that looks like a
-blank line -- a line containing nothing spaces or tabs is considered
+blank line -- a line containing nothing. Note: all spaces or tabs is considered
blank.) Normal paragraphs should not be intended with spaces or tabs.
Headers and Blockquotes
@@ -405,7 +405,8 @@ Output:
To specify an entire block of pre-formatted code, indent every line of
-the block by 4 spaces or 1 tab. Just like with code spans, `&`, `<`,
+the block by 4 spaces or 1 tab, or add a line containing three backticks before
+and after the code block. Just like with code spans, `&`, `<`,
and `>` characters will be escaped automatically.
Markdown:
@@ -417,6 +418,17 @@ Markdown:
<p>For example.</p>
</blockquote>
+or
+
+ If you want your page to validate under XHTML 1.0 Strict,
+ you've got to put paragraph tags in your blockquotes:
+
+ ```
+ <blockquote>
+ <p>For example.</p>
+ </blockquote>
+ ```
+
Output:
<p>If you want your page to validate under XHTML 1.0 Strict,
@@ -427,6 +439,7 @@ Output:
&lt;/blockquote&gt;
</code></pre>
+
### Floating Menu ###
To create a floating menu for a single page that always appears
diff --git a/site/user/build.md b/site/user/build.md
index 0cdf322b22..d43144adec 100644
--- a/site/user/build.md
+++ b/site/user/build.md
@@ -19,7 +19,7 @@ using the ordinary library search path.
In contrast, the developer-oriented default is an unoptimized build with full
debug symbols and all third-party dependencies built from source and embedded
-into libskia. This is how do all our manual and automated testing.
+into libskia. This is how we do all our manual and automated testing.
Skia offers several features that make use of third-party libraries, like
libpng, libwebp, or libjpeg-turbo to decode images, or ICU and sftnly to subset
diff --git a/site/user/download.md b/site/user/download.md
index 75a53da0f8..bdedf7df9e 100644
--- a/site/user/download.md
+++ b/site/user/download.md
@@ -1,34 +1,40 @@
How to download Skia
====================
-Install depot_tools and Git
+Install `depot_tools` and Git
---------------------------
Follow the instructions on [Installing Chromium's
depot_tools](http://www.chromium.org/developers/how-tos/install-depot-tools)
-to download depot_tools (which includes gclient, git-cl, and Ninja).
+to download `depot_tools` (which includes gclient, git-cl, and Ninja).
+Below is a summary of the necessary steps.
<!--?prettify lang=sh?-->
git clone 'https://chromium.googlesource.com/chromium/tools/depot_tools.git'
export PATH="${PWD}/depot_tools:${PATH}"
-depot_tools will also install Git on your system, if it wasn't installed
+`depot_tools` will also install Git on your system, if it wasn't installed
already.
Clone the Skia repository
-------------------------
+Skia can either be cloned using `git` or the `fetch` tool that is
+installed with `depot_tools`.
+
<!--?prettify lang=sh?-->
git clone https://skia.googlesource.com/skia.git
+ # or
+ # fetch skia
cd skia
python tools/git-sync-deps
Getting started with Skia
-------------------------
-You probably now want to [build](./build) Skia.
+You will probably now want to [build](./build) Skia.
Changing and contributing to Skia
---------------------------------
diff --git a/site/user/quick/METADATA b/site/user/quick/METADATA
deleted file mode 100644
index 0c2cb3463e..0000000000
--- a/site/user/quick/METADATA
+++ /dev/null
@@ -1,2 +0,0 @@
-{ "fileOrder": ["ios"] }
-
diff --git a/site/user/quick/index.md b/site/user/quick/index.md
deleted file mode 100644
index 35c9e5a2c8..0000000000
--- a/site/user/quick/index.md
+++ /dev/null
@@ -1,5 +0,0 @@
-Quick Start Guides (Deprecated)
-===============================
-
-This section is obsolete and will be removed soon.
-See [How to build Skia](/user/build) for the best way to build Skia.
diff --git a/site/user/sample/color.md b/site/user/sample/color.md
index 3283a98535..5870b0314b 100644
--- a/site/user/sample/color.md
+++ b/site/user/sample/color.md
@@ -6,10 +6,10 @@ Why is Skia Color Correct?
A color space is a **gamut** and a **transfer function**.
-Gamut refers to the **available range of colors** of a particular in an image or on a display
-device. Being gamut correct means that we will display colors as the designer intended and
-consistently across display devices. A common problem with new “wide gamut” devices and
-uncorrected colors is illustrated below.
+Gamut refers to the **available range of colors** in an image or on a display device. Being
+gamut correct means that we will display colors as the designer intended and consistently across
+display devices. A common problem with new “wide gamut” devices and uncorrected colors is
+illustrated below.
Device Dependent Color (Wrong)
@@ -84,7 +84,7 @@ to make color spaces.
// Create a color space from an ICC profile
sk_sp<SkColorSpace> MakeICC();
-Starting with **sources** (the things that draw you draw), there are a number of ways to make sure
+Starting with **sources** (the things that you draw), there are a number of ways to make sure
that they are tagged with a color space.
**SkColor** (stored on **SkPaint**) is assumed to be in the sRGB color space - meaning that it
@@ -164,8 +164,8 @@ Opting In To Color Correct Skia
-------------------------------
By itself, **adding a color space tag to a source will not change draw behavior**. In fact,
-tagging sources with color spaces is always a best practice, regardless of whether we want Skia's
-color correct behavior.
+tagging sources with color spaces is always a best practice, regardless of whether or not we want
+Skia's color correct behavior.
Adding a color space tag to the **destination is the trigger that turns on Skia color correct
behavior**.
diff --git a/site/user/sample/pdf.md b/site/user/sample/pdf.md
index 7bd7b74012..d42aad371f 100644
--- a/site/user/sample/pdf.md
+++ b/site/user/sample/pdf.md
@@ -50,7 +50,7 @@ In this document:
+ **drop** means to draw nothing.
- + **ignore** mean to draw without the effect
+ + **ignore** means to draw without the effect
+ **expand** means to implement something in a non-PDF-ish way.
This may mean to rasterize vector graphics, to expand paths with
diff --git a/site/user/tips.md b/site/user/tips.md
index c477138fc8..9458ace310 100644
--- a/site/user/tips.md
+++ b/site/user/tips.md
@@ -81,29 +81,23 @@ process it with `dm`.
There are two ways Skia takes advantage of specific hardware.
-1. Subclass SkCanvas
-
- Since all drawing calls go through SkCanvas, those calls can be
- redirected to a different graphics API. SkGLCanvas has been
- written to direct its drawing calls to OpenGL. See src/gl/
-
-2. Custom bottleneck routines
+1. Custom bottleneck routines
There are sets of bottleneck routines inside the blits of Skia
that can be replace on a platform in order to take advantage of
specific CPU features. One such example is the NEON SIMD
- instructions on ARM v7 devices. See src/opts/
+ instructions on ARM v7 devices. See [src/opts/](https://skia.googlesource.com/skia/+/master/src/opts/)
* * *
<span id="font-hinting">Does Skia support Font hinting?</span>
--------------------------------------------------------------
-Skia has a built-in font cache, but it does not know how to actual render font
+Skia has a built-in font cache, but it does not know how to actually render font
files like TrueType into its cache. For that it relies on the platform to
-supply an instance of SkScalerContext. This is Skia's abstract interface for
+supply an instance of `SkScalerContext`. This is Skia's abstract interface for
communicating with a font scaler engine. In src/ports you can see support
-files for FreeType, Mac OS X, and Windows GDI font engines. Other font
+files for FreeType, macOS, and Windows GDI font engines. Other font
engines can easily be supported in a like manner.
@@ -121,7 +115,7 @@ generate the glyphs and their positions, including kerning.
together](https://github.com/aam/skiaex). In the example, a
`SkTypeface` and a `hb_face_t` are created using the same `mmap()`ed
`.ttf` font file. The HarfBuzz face is used to shape unicode text into
-a sequence of glyphs and positions, and the SkTypeface can then be
+a sequence of glyphs and positions, and the `SkTypeface` can then be
used to draw those glyphs.
* * *
generated by cgit v1.2.3 (git 2.39.1) at 2024-05-17 05:05:54 +0000