Import Cobalt 21.master.0.253153
diff --git a/src/third_party/skia/site/dev/contrib/c++11.md b/src/third_party/skia/site/dev/contrib/c++11.md
deleted file mode 100644
index 432ad88..0000000
--- a/src/third_party/skia/site/dev/contrib/c++11.md
+++ /dev/null
@@ -1,57 +0,0 @@
-C++11 in Skia
-=============
-
-Skia uses C++11. But as a library, we are technically limited by what our
-clients support and what our build bots support.
-
-Skia may also be limited by restrictions we choose put on ourselves. This
-document is not concerned with C++11 policy in Skia, only its technical
-feasibility. This is about what we can use, a superset of what we may use.
-
-The gist:
-
-- C++11 the language as supported by GCC 4.7 or later is pretty usable.
-- The C++11 standard library can generally be used, with some teething.
-- If you break a bot, that feature is not usable.
-- Local statics are not thread safe.
-
-
-Clients
--------
-
-The clients we pay most attention to are Chrome, Android, Mozilla, and a few
-internal Google projects.
-
-Chrome builds with a recent Clang on Mac and Linux and with a recent MSVC on
-Windows. These toolchains are new enough to not be the weak link to use any
-C++11 language feature. Chromium, however, builds against libstdc++4.6.4
-(STL and runtime) on Linux. This precludes direct use of a number of type
-traits.
-
-Chrome intentionally disables thread-safe initialization of static variables,
-so we cannot rely on that. Our bots disable this too, so keep an eye on TSAN.
-
-Android builds with either a somewhat aged GCC or a recent Clang. They're
-generally not a weak link for C++11 language features. Android's C++ standard
-library had historically been a pain, but seems to work fine these days.
-
-Mozilla's current weak link is a minimum requirement of GCC 4.7. Most features
-marked in red on Mozilla's C++11 [feature
-matrix](https://developer.mozilla.org/en-US/docs/Using_CXX_in_Mozilla_code) are
-marked that way because they arrived in GCC 4.8. Their minimum-supported Clang
-and MSVC toolchains are pretty good, but MSVC 2013 will become the weak link soon.
-
-Internal Google projects tend to support C++11 completely, including the
-full C++11 standard library.
-
-
-Bots
-----
-
-Most of our bots are pretty up-to-date: the Windows bots use MSVC 2013, the Mac
-bots a recent Clang, and the Linux bots GCC 4.8 or a recent Clang. Our Android
-bots use a recent toolchain from Android (see above), and our Chrome bots use
-Chrome's toolchains (see above). I'm not exactly sure what our Chrome OS bots
-are using. They're probably our weak link right now, though problems are rare.
-
-I believe our bots' ability to use C++11 matches Mozilla's list nearly identically.
diff --git a/src/third_party/skia/site/dev/contrib/cqkeywords.md b/src/third_party/skia/site/dev/contrib/cqkeywords.md
index b21b787..8f0385a 100644
--- a/src/third_party/skia/site/dev/contrib/cqkeywords.md
+++ b/src/third_party/skia/site/dev/contrib/cqkeywords.md
@@ -36,7 +36,7 @@
CQ_INCLUDE_TRYBOTS=master.tryserver.chromium.linux:linux_chromium_asan_rel_ng
- CQ_INCLUDE_TRYBOTS=skia.primary:Test-Win-MSVC-ShuttleC-GPU-GTX960-x86_64-Debug-ANGLE
+ CQ_INCLUDE_TRYBOTS=skia.primary:Test-Win10-Clang-ShuttleC-GPU-GTX960-x86_64-Debug-All-ANGLE
No-Tree-Checks
diff --git a/src/third_party/skia/site/dev/contrib/directory.md b/src/third_party/skia/site/dev/contrib/directory.md
index 4edab89..0694cd4 100644
--- a/src/third_party/skia/site/dev/contrib/directory.md
+++ b/src/third_party/skia/site/dev/contrib/directory.md
@@ -4,8 +4,7 @@
* Docs & Bugs
- [Skia.org](https://skia.org/)
- [Issue Tracker](https://bug.skia.org/)
- - [Autogenerated API
- Documentation](https://skia-doc.commondatastorage.googleapis.com/doxygen/doxygen/html/index.html)
+ - [Autogenerated API Documentation](https://api.skia.org)
* Code Repositories
- [Git repository](https://skia.googlesource.com/skia/)
diff --git a/src/third_party/skia/site/dev/contrib/flatten.md b/src/third_party/skia/site/dev/contrib/flatten.md
deleted file mode 100644
index 192571e..0000000
--- a/src/third_party/skia/site/dev/contrib/flatten.md
+++ /dev/null
@@ -1,88 +0,0 @@
-Flattenables
-============
-
-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
-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):
-
-<!--?prettify?-->
-~~~~
-virtual void flatten(SkFlattenableWriteBuffer& buffer) const override {
- this->INHERITED::flatten(buffer);
- // Write any private data that needs to be stored to recreate this object
-}
-~~~~
-
-2: Override the (protected) constructor that creates an object from an
-SkFlattenableReadBuffer:
-
-<!--?prettify?-->
-~~~~
-SkNewClass(SkFlattenableReadBuffer& buffer)
-: INHERITED(buffer) {
- // Read the data from the buffer in the same order as it was written to the
- // SkFlattenableWriteBuffer and construct the new object
-}
-~~~~
-
-3: Declare a set of deserialization procs for your object in the class declaration:
-We have a macro for this:
-
-<!--?prettify?-->
-~~~~
-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
-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
-need to add:
-
-<!--?prettify?-->
-~~~~
-public:
-
-SK_DECLARE_FLATTENABLE_REGISTRAR_GROUP()
-~~~~
-
-Then in the cpp file you define all the members of the group together:
-
-<!--?prettify?-->
-~~~~
-SK_DEFINE_FLATTENABLE_REGISTRAR_GROUP_START(SkGroupClass)
-
- SK_DEFINE_FLATTENABLE_REGISTRAR_ENTRY(SkMemberClass1)
-
- SK_DEFINE_FLATTENABLE_REGISTRAR_ENTRY(SkMemberClass2)
-
- // etc
-
-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.
-For a single flattenable add
-
-<!--?prettify?-->
-~~~~
-SK_DEFINE_FLATTENABLE_REGISTRAR_ENTRY(SkNewClass)
-~~~~
-
-For a group, add
-
-<!--?prettify?-->
-~~~~
-SkGroupClass::InitializeFlattenables();
-~~~~
-
diff --git a/src/third_party/skia/site/dev/contrib/index.md b/src/third_party/skia/site/dev/contrib/index.md
index 9f74a40..23a4aed 100644
--- a/src/third_party/skia/site/dev/contrib/index.md
+++ b/src/third_party/skia/site/dev/contrib/index.md
@@ -7,42 +7,54 @@
Report Bugs
-----------
-Find bugs to fix or report new bugs in the [Skia issue tracker](http://bug.skia.org/).
-You can also search the [Chromium issue tracker](http://code.google.com/p/chromium/issues/list) for bugs related to graphics or Skia.
+Find bugs to fix or report new bugs in the [Skia issue
+tracker](http://bug.skia.org/). You can also search the [Chromium issue
+tracker](http://code.google.com/p/chromium/issues/list) for bugs related to
+graphics or Skia.
Test
----
-Write an application or tool that will exercise the Skia code differently than our
-current set of tests and verify that Skia works as expected. Draw something
-interesting and profile it to find ways to speed up Skia's implementation.
-We cannot always fix issues or support every scenario, but we welcome any bugs
-found so we can assess and prioritize them. (If you find _and_ fix a bug, even better!)
+Write an application or tool that will exercise the Skia code differently than
+our current set of tests and verify that Skia works as expected.
+Draw something interesting and profile it to find ways to speed up Skia's
+implementation.
+We cannot always fix issues or support every scenario, but we welcome any bugs
+found so we can assess and prioritize them. (If you find _and_ fix a bug, even
+better!)
Contribute Code
---------------
-Whether you develop a new feature or a fix for an existing bug in the Skia code base,
-you will need a committer to review and approve the change. There are some steps that
-can speed up the review process:
+Whether you develop a new feature or a fix for an existing bug in the Skia code
+base, you will need a committer to review and approve the change.
+There are some steps that can speed up the review process:
Keep your code submissions small and targeted.
-When possible, have a fellow contributor review your change in advance of submission.
-Propose new features to the project leads by opening a feature bug or posting to
-skia-discuss ahead of development. For more information, see [How to submit a patch](./contrib/submit).
+When possible, have a fellow contributor review your change in advance of
+submission.
+Propose new features to the project leads by opening a feature bug
+or posting to skia-discuss ahead of development.
+For more information, see [How to submit a patch](/dev/contrib/submit).
-For background on the project and an outline of the types of roles interested parties
-can take on, see [Project Roles](../../roles).
+For background on the project and an outline of the types of roles interested
+parties can take on, see [Project Roles](/roles).
-Anyone contributing code to Skia must sign a Contributor License Agreement and ensure
-they are listed in the AUTHORS file:
-Individual contributors can complete the [Individual Contributor License Agreement](https://developers.google.com/open-source/cla/individual) online.
-If you are contributing on behalf of a corporation, fill out the [Corporate Contributor License Agreement](https://developers.google.com/open-source/cla/corporate)
-and send it in as described on that page.
-If it is your first time submitting code or you have not previously done so, add your
-(or your organization's) name and contact info to the [AUTHORS file](https://skia.googlesource.com/skia/+/master/AUTHORS) as a part
-of your CL.
-REVIEWERS: Before you LGTM a change, verify that the contributor is listed in the AUTHORS file.
-If they are not, a Googler must ensure that the individual or their corporation has signed the
-CLA by searching [go/cla-signers](https://goto.google.com/cla-signers).
+Anyone contributing code to Skia must sign a Contributor License Agreement and
+ensure they are listed in the AUTHORS file:
+Individual contributors can complete the [Individual Contributor License
+Agreement](https://developers.google.com/open-source/cla/individual) online.
+If you are contributing on behalf of a corporation, fill out the [Corporate
+Contributor License
+Agreement](https://developers.google.com/open-source/cla/corporate) and send it
+in as described on that page.
+If it is your first time submitting code or you have not previously done so,
+add your (or your organization's) name and contact info to the [AUTHORS
+file](https://skia.googlesource.com/skia/+/master/AUTHORS) as a part of your CL.
+
+REVIEWERS: Before you LGTM a change, verify that the contributor is listed in
+the AUTHORS file.
+If they are not, a Googler must ensure that the individual or
+their corporation has signed the CLA by searching
+[go/cla-signers](https://goto.google.com/cla-signers).
Then have an entry added to the AUTHORS file with the CL.
diff --git a/src/third_party/skia/site/dev/contrib/jumper.md b/src/third_party/skia/site/dev/contrib/jumper.md
deleted file mode 100644
index 757697f..0000000
--- a/src/third_party/skia/site/dev/contrib/jumper.md
+++ /dev/null
@@ -1,102 +0,0 @@
-Contributing to SkJumper
-========================
-
-SkJumper is the execution engine of SkRasterPipeline, a system we've been using
-to accelerate CPU-bound work inside Skia, most notably color-space conversions
-and color-correct drawing.
-
-(This is where I'd put my link to design document if I had one...)
-
-SkJumper is more annoying to contribute to than most Skia code because of its
-offline compilation step. You'll need particular tools installed on your
-machine and to tell GN about them. This document is designed to guide you
-through this process and ease some of that annoyance.
-
-One-time Setup
---------------
-
-To generate stage code you need Clang 4.0, objdump, and ccache. It's best that
-Clang is exactly the same version we typically use (as of writing 4.0.0) and
-you'll need objdump to be compiled with support for x86-64, ARMv7, and ARMv8.
-
-The easiest way to satisfy these contraints is to get your hands on a Mac and
-install [Homebrew](https://brew.sh). Once you have `brew` installed, run this
-to get the tools you need:
-
-<!--?prettify lang=sh?-->
-
- brew install llvm binutils ccache
-
-Setting up GN
--------------------------
-
-With your tools installed, tell GN about them
-
- skia_jumper_clang = path/to/clang-4.0
- skia_jumper_objdump = path/to/gobjdump
- skia_jumper_ccache = path/to/ccache
-
-then regenerate and build as normal.
-
-If you look in your GN out directory, you should now see a bunch of `.o` files,
-and `git status` should show no changes to `src/jumper/SkJumper_generated*.S`.
-That's good. Those object files are the intermediates we parse to produce
-the assembly files. We just leave them around in case you want to look at
-them yourself.
-
-Make A Change
--------------
-
-Let's use the `from_srgb` stage as a little playground to make a real change.
-Linearizing sRGB encoded bytes is slow, so let's pretend we've decided to trade
-quality for speed, approximating the existing implementation with a simple square.
-
-Open up `SkJumper_stages.cpp` and find the `from_srgb` stage. It'll look like
-
-<!--?prettify lang=cc?-->
-
- STAGE(from_srgb) {
- r = from_srgb(r);
- g = from_srgb(g);
- b = from_srgb(b);
- }
-
-Let's replace whatever's there with our fast approximation:
-
-<!--?prettify lang=cc?-->
-
- STAGE(from_srgb) {
- r *= r;
- g *= g;
- b *= b;
- }
-
-When you save and re-Ninja, you should now see changes to
-`src/jumper/SkJumper_generated.S` and `src/jumper/SkJumper_generated_win.S`.
-If you can't read assembly, no big deal. If you can, run `git diff`. You
-should see the various `sk_from_srgb_*` functions get dramatically simpler,
-something like three multiplies and a couple other bookkeeping instructions.
-
-It's not unusual for isolated changes in one stage to cause seemingly unrelated
-changes in another. When adding or removing any code you'll usually see all
-the comments in branch instructions change a little bit, but the actual
-instruction on the left won't change. When adding or removing uses of
-constants, you'll often see both the comment and instruction on the left change
-for other loads of constants from memory, especially on x86-64. You'll also
-see some code that looks like garbage change; those are the constants. If
-any of this worries you, please do go running to someone who knows more for
-help, but odds are everything is fine.
-
-At this point things should just be business as usual. Any time you change
-`SkJumper_stages.cpp`, Ninja ought to notice and regenerate the assembly files.
-
-Adding a new Stage
-------------------
-
-Adding a new stage is a lot like changing an existing stage. Edit
-`SkJumper_stages.cpp`, build Skia, test, repeat until correct.
-
-You'll just need to also edit `SkRasterPipeline.h` to add your new stage to the
-macro listing all the stages. The stage name is the handle normal Skia code
-uses to refer to the stage abstractly, and the wiring between
-`SkRasterPipeline::foo` and `STAGE(foo) { ... }` should work automatically.
diff --git a/src/third_party/skia/site/dev/contrib/patch.md b/src/third_party/skia/site/dev/contrib/patch.md
index cf8b35b..b7b29f0 100644
--- a/src/third_party/skia/site/dev/contrib/patch.md
+++ b/src/third_party/skia/site/dev/contrib/patch.md
@@ -7,30 +7,31 @@
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 @@
~~~~
* 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 @@
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/src/third_party/skia/site/dev/contrib/simd.md b/src/third_party/skia/site/dev/contrib/simd.md
deleted file mode 100644
index e2e6310..0000000
--- a/src/third_party/skia/site/dev/contrib/simd.md
+++ /dev/null
@@ -1,141 +0,0 @@
-Skia's New Approach to SIMD
-===========================
-
-Most hot software paths in Skia are implemented with processor-specific SIMD instructions. For graphics performance, the parallelism from SIMD is essential: there is simply no realistic way to eek the same performance out of portable C++ code as we can from the SSE family of instruction sets on x86 or from NEON on ARM or from MIPS32's DSP instructions. Depending on the particular code path and math involved, we see 2, 4, 8, or even ~16x performance increases over portable code when really exploiting the processor-specific SIMD instructions.
-
-But the SIMD code we've piled up over the years has some serious problems. It's often quite low-level, with poor factoring leading to verbose, bug prone, and difficult to read code. SIMD instrinsic types and functions take a good long while to get used to reading, let alone writing, and assembly is generally just a complete non-starter. SIMD coverage of Skia methods is not dense: a particular drawing routine might be specialized for NEON but not for SSE, or might have a MIPS DSP implementation but no NEON. Even when we have full instruction set coverage, the implementations of these specialized routines may not produce identical results, either when compared with each other or with our portable fallback code. The SIMD implementations are often simply incorrect, but the code is so fragile and difficult to understand, we can't fix it. There are long lived bugs in our tracker involving crashes and buffer under- and overflows that we simply cannot fix because no one on the team understands the code involved. And finally, to top it all off, the code isn't always even really that fast.
-
-This all needs to change. I want Skia developers to be able to write correct, clear, and fast code, and in software rendering, SIMD is the only way to get "fast". This document outlines a new vision for how Skia will use SIMD instructions with no compromises, writing clear code _once_ that runs quickly on all platforms we support.
-
-The Plan
---------
-
-We're going to wrap low-level platform-specific instrinsics with zero-cost abstractions with interfaces matching Skia's higher-level-but-still-quite-low-level use cases. Skia code will write to this interface _once_, which then compiles to efficient SSE, NEON, or portable code (MIPS is quite TBD, for now group it conceptually under portable code) via platform-specific backends. The key here is to find the right sweet spot of abstraction that allows us to express the graphical concepts we want in Skia while allowing each of those platform-specific backends flexibility to implement those concepts as efficiently as possible.
-
-While Skia uses a mix of float, 32-bit, 16-bit, and 8-bit integer SIMD instructions, 32-bit integers fall quite behind the rest in usage. Since we tend to operate on 8888 ARGB values, 8-bit SIMD tends to be the most natural and fastest approach, but when multiplication gets involved (essentially all the time), 16-bit SIMD inevitably gets tangled in there. For some operations like division, square roots, or math with high range or precision requirements, we expand our 8-bit pixel components up to floats, and working with a single pixel as a 4-float vector becomes most natural. This plan focuses on how we'll deal with these majority cases: floats, and 8- and 16-bit integers.
-
-`SkNf` for floats
----------------
-
-Wrapping floats with an API that allows efficient implementation on SSE and NEON is by far the easiest task involved here. Both SSE and NEON naturally work with 128-bit vectors of 4 floats, and they have a near 1-to-1 correspondence between operations. Indeed, the correspondence is so close that it's tempting to solve this problem by picking one set of intrinsics, e.g. NEON, and just `#define`ing portable and SSE implementations of NEON:
-
- #define float32x4_t __m128
- #define vmulq_f32 _mm_mul_ps
- #define vaddq_f32 _mm_add_ps
- #define vld1q_f32 _mm_loadu_ps
- #define vst1q_f32 _mm_storeu_ps
- ...
-
-This temptation starts to break down when you notice:
-
-- there are operations that don't quite correspond, e.g. `_mm_movemask_ps`; and
-- 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.
-
-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.
-
-Our most common float use cases are working with 2D coordinates and with 4-float-component pixels. Since these are so common, we've made simple typedefs for these two use cases, `Sk2f` and `Sk4f`, and also versions reminding you that it can work with vectors of `SkScalar` (a Skia-specific float typedef) too: `Sk2s`, `Sk4s`.
-
-`SkNf` in practice
-----------------
-
-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.
-
-`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
-----------------------------------------
-
-Building an abstraction layer over 8- and 16-bit fixed point math has proven to be quite a challenge. In fixed point, NEON and SSE again have some overlap, and they could probably be implemented in terms of each other if you were willing to sacrifice performance on SSE in favor of NEON or vice versa. But unlike with floats, where `SkNf` is really a pretty thin veneer over very similar operations, to really get the best performance out of each fixed point instruction set you need to work in rather different idioms.
-
-`SkPx`, our latest approach (there have been alpha `Sk16b` and beta `Sk4px` predecessors) to 8- and 16-bit SIMD tries to abstract over those idioms to again allow Skia developers to write one piece of clear graphics code that different backends can translate into their native intrinsics idiomatically.
-
-`SkPx` is really a family of three related types:
-
- 1. `SkPx` itself represents between 1 and `SkPx::N` 8888 ARGB pixels, where `SkPx::N` is a backend-specific compile-time power of 2.
- 2. `SkPx::Wide` represents those same pixels, but with 16-bits of space per component.
- 3. `SkPx::Alpha` represents the alpha channels of those same pixels.
-
-`SkPx`, `Wide` and `Alpha` create a somewhat complicated algebra of operations entirely motivated by the graphical operations we need to perform. Here are some examples:
-
- SkPx::LoadN(const uint32_t*) -> SkPx // Load full cruising-speed SkPx.
- SkPx::Load(n, const uint32_t*) -> SkPx // For the 0<n<N ragged tail.
-
- SkPx.storeN(uint32_t*) // Store a full SkPx.
- SkPx.store(n, uint32_t*) // For the ragged 0<n<N tail.
-
- SkPx + SkPx -> SkPx
- SkPx - SkPx -> SkPx
- SkPx.saturatedAdd(SkPx) -> SkPx
-
- SkPx.alpha() -> Alpha // Extract alpha channels.
- Alpha::LoadN(const uint8_t*) -> Alpha // Like SkPx loads, in 8-bit steps.
- Alpha::Load(n, const uint8_t*) -> Alpha
-
- SkPx.widenLo() -> Wide // argb -> 0a0r0g0b
- SkPx.widenHi() -> Wide // argb -> a0r0g0b0
- SkPx.widenLoHi() -> Wide // argb -> aarrggbb
-
- Wide + Wide -> Wide
- Wide - Wide -> Wide
- Wide << bits -> Wide
- Wide >> bits -> Wide
-
- SkPx * Alpha -> Wide // 8 x 8 -> 16 bit
- Wide.div255() -> SkPx // 16-bit -> 8 bit
-
- // 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:
-
- while (n >= SkPx::N) {
- // Apply some_function() to SkPx::N pixels.
- some_function(SkPx::LoadN(src), SkPx::LoadN(dst)).storeN(dst);
- src += SkPx::N; dst += SkPx::N; n -= SkPx::N;
- }
- if (n > 0) {
- // Finish up the tail of 0<n<N pixels.
- some_function(SkPx::Load(n, src), SkPx::Load(n, dst)).store(n, dst);
- }
-
-The portable code is of course the simplest place to start looking at implementation details: its `SkPx` is just `uint8_t[4]`, its `SkPx::Wide` `uint16_t[4]`, and its `SkPx::Alpha` just `uint8_t`. Its preferred number of pixels to work with is `SkPx::N = 1`. (Amusingly, GCC and Clang seem pretty good about autovectorizing this backend using 32-bit math, which typically ends up within ~2x of the best we can do ourselves.)
-
-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`.
-
-(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?)
-
-Keeping `Alpha` as a single dense `uint8x8_t` plane allows the NEON backend to be much more efficient with operations involving `Alpha`. We'd love to do this in SSE too, where we store `Alpha` somewhat inefficiently with each alpha component replicated 4 times, but SSE simply doesn't expose efficient ways to transpose interlaced pixels into planar pixels and vice versa. We could write them ourselves, but only as rather complex compound operations that slow things down more than they help.
-
-These details will inevitably change over time. The important takeaway here is, to really work at peak throughput in SIMD fixed point, you need to work with the idiom of the instruction set, and `SkPx` is a design that can present a consistent interface to abstract away backend details for you.
-
-`SkPx` in practice
-----------------
-
-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
-
-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.
-
-In Summary
-----------
-
-I am confident that Skia developers soon will be able to write single, clear, maintainable, and of course _fast_, graphical algorithms using `SkNf` and `SkPx`. As I have been porting our algorithms, I have perversely enjoyed replacing thousands of lines of unmaintainable code with usually mere dozens of readable code.
-
-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
diff --git a/src/third_party/skia/site/dev/contrib/style.md b/src/third_party/skia/site/dev/contrib/style.md
index 639738c..9edf83d 100644
--- a/src/third_party/skia/site/dev/contrib/style.md
+++ b/src/third_party/skia/site/dev/contrib/style.md
@@ -2,17 +2,17 @@
=======================
These conventions have evolved over time. Some of the earlier code in both
-projects doesn’t strictly adhere to the guidelines. However, as the code evolves
+projects doesn't strictly adhere to the guidelines. However, as the code evolves
we hope to make the existing code conform to the guildelines.
Files
-----
-We use .cpp and .h as extensions for c++ source and header files. We use
-foo_impl.h for headers with inline definitions for class foo.
+We use .cpp and .h as extensions for c++ source and header files.
-Headers that aren’t meant for public consumption should be placed in src
-directories so that they aren’t in a client’s search path.
+Headers that aren't meant for public consumption should be placed in src
+directories so that they aren't in a client's search path, or in
+include/private if they need to be used by public headers.
We prefer to minimize includes. If forward declaring a name in a header is
sufficient then that is preferred to an include.
@@ -22,8 +22,9 @@
<span id="no-define-before-sktypes"></span>
Do not use #if/#ifdef before including "SkTypes.h" (directly or indirectly).
+Most things you'd #if on tend to not yet be decided until SkTypes.h.
-We use spaces not tabs (4 of them).
+We use 4 spaces, not tabs.
We use Unix style endlines (LF).
@@ -41,7 +42,7 @@
------
Both projects use a prefix to designate that they are Skia prefix for classes,
-enums, structs, typedefs etc is Sk. Ganesh’s is Gr. Nested types should not be
+enums, structs, typedefs etc is Sk. Ganesh's is Gr. Nested types should not be
prefixed.
<!--?prettify?-->
@@ -54,7 +55,7 @@
};
~~~~
-Data fields in structs, classes, unions begin with lowercase f and are then
+Data fields in structs, classes, unions begin with lowercase f and are then
camel capped.
<!--?prettify?-->
@@ -81,7 +82,8 @@
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<singular enum name>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),
+or a kLast member of the enum is fine too.
<!--?prettify?-->
~~~~
@@ -98,7 +100,7 @@
kBlueberry_PancakeType,
kPlain_PancakeType,
kChocolateChip_PancakeType,
-
+
kLast_PancakeType = kChocolateChip_PancakeType
};
@@ -167,8 +169,8 @@
#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 +181,14 @@
#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?-->
~~~~
@@ -227,7 +229,7 @@
Flow Control
------------
-There is a space between flow control words and parentheses and between
+There is a space between flow control words and parentheses and between
parentheses and braces:
<!--?prettify?-->
@@ -252,7 +254,7 @@
...
break;
case kGreen:
- ...
+ ...
break;
...
default:
@@ -284,7 +286,7 @@
switch (filter) {
...
case kGaussian_Filter: {
- Bitmap srcCopy = src->makeCopy();
+ Bitmap srcCopy = src->makeCopy();
...
break;
}
@@ -296,9 +298,9 @@
-------
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
-intermixed with methods.
+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. It's nice to keep all data fields together at the end.
<!--?prettify?-->
~~~~
@@ -308,14 +310,14 @@
...
protected:
- ...
-
-private:
- SkBar fBar;
...
+private:
void barHelper(...);
...
+
+ SkBar fBar;
+ ...
};
~~~~
@@ -330,8 +332,8 @@
};
~~~~
-Virtual functions that are overridden in derived classes should use override
-(and not the override keyword). The virtual keyword can be omitted.
+Virtual functions that are overridden in derived classes should use override,
+and the virtual keyword should be omitted.
<!--?prettify?-->
~~~~
@@ -339,8 +341,8 @@
}
~~~~
-This should be the last element of their private section, and all references to
-base-class implementations of a virtual function should be explicitly qualified:
+All references to base-class implementations of a virtual function
+should be explicitly qualified:
<!--?prettify?-->
~~~~
@@ -351,9 +353,6 @@
}
~~~~
-As in the above example, derived classes that redefine virtual functions should
-use override to note that explicitly.
-
Constructor initializers should be one per line, indented, with punctuation
placed before the initializer. This is a fairly new rule so much of the existing
code is non-conforming. Please fix as you go!
@@ -367,7 +366,7 @@
}
~~~~
-Constructors that take one argument should almost always be explicit, with
+Constructors that take one argument should almost always be explicit, with
exceptions made only for the (rare) automatic compatibility class.
<!--?prettify?-->
@@ -379,7 +378,7 @@
};
~~~~
-Method calls within method calls should be prefixed with dereference of the
+Method calls within method calls should be prefixed with dereference of the
'this' pointer. For example:
<!--?prettify?-->
@@ -387,47 +386,6 @@
this->method();
~~~~
-Comparisons
------------
-
-We prefer that equality operators between lvalues and rvalues place the lvalue
-on the right:
-
-<!--?prettify?-->
-~~~~
-if (7 == luckyNumber) {
- ...
-}
-~~~~
-
-However, inequality operators need not follow this rule:
-
-<!--?prettify?-->
-~~~~
-if (count > 0) {
- ...
-}
-~~~~
-
-Comments
-
-We use doxygen-style comments.
-
-For grouping or separators in an implementation file we use 80 slashes
-
-<!--?prettify?-->
-~~~~
-void SkClassA::foo() {
- ...
-}
-
-////////////////////////////////////////////////////////////////
-
-void SkClassB::bar() {
- ...
-}
-~~~~
-
Integer Types
-------------
@@ -435,16 +393,16 @@
(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 suggest explicit `nullptr` comparisons when
+checking for `nullptr` pointers, as documentation:
<!--?prettify?-->
~~~~
@@ -453,8 +411,8 @@
}
~~~~
-When checking non-nullptr pointers explicit comparisons are not required because it
-reads like a double negative:
+When checking non-`nullptr` pointers we think implicit comparisons read better than
+an explicit comparison's double negative:
<!--?prettify?-->
~~~~
@@ -463,66 +421,27 @@
}
~~~~
-Returning structs
------------------
-
-If the desired behavior is for a function to return a struct, we prefer using a
-struct as an output parameter
-
-<!--?prettify?-->
-~~~~
-void modify_foo(SkFoo* foo) {
- // Modify foo
-}
-~~~~
-
-Then the function can be called as followed:
-
-<!--?prettify?-->
-~~~~
-SkFoo foo;
-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
-skipped on failure (assuming the constructor for SkFoo does no initialization).
-
-<!--?prettify?-->
-~~~~
-bool modify_foo(SkFoo* foo) {
- if (some_condition) {
- // Modify foo
- return true;
- }
- // Leave foo unmodified
- return false;
-}
-~~~~
-
Function Parameters
-------------------
-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.
-Variable (i.e. mutable) object parameters are passed to functions as pointers.
+Mandatory constant object parameters are passed to functions as const references.
+Optional constant object parameters are passed to functions as const pointers.
+Mutable object parameters are passed to functions as pointers.
+We very rarely pass anything by non-const reference.
<!--?prettify?-->
~~~~
// src and paint are optional
-void SkCanvas::drawBitmapRect(const SkBitmap& bitmap, const SkIRect* src,
- const SkRect& dst, const SkPaint* paint = nullptr);
+void SkCanvas::drawBitmapRect(const SkBitmap& bitmap, const SkIRect* src,
+ const SkRect& dst, const SkPaint* paint = nullptr);
+
// metrics is mutable (it is changed by the method)
SkScalar SkPaint::getFontMetrics(FontMetric* metrics, SkScalar scale) const;
-// A reference to foo is retained by SkContainer
-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 +452,7 @@
}
~~~~
-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/src/third_party/skia/site/dev/contrib/submit.md b/src/third_party/skia/site/dev/contrib/submit.md
index d3ffc9d..59ac5f8 100644
--- a/src/third_party/skia/site/dev/contrib/submit.md
+++ b/src/third_party/skia/site/dev/contrib/submit.md
@@ -32,7 +32,7 @@
<!--?prettify lang=sh?-->
git pull
- python tools/git-sync-deps
+ python2 tools/git-sync-deps
Adding a unit test
------------------
@@ -45,10 +45,9 @@
See [Writing Unit and Rendering Tests](../testing/tests) for details.
Unit tests are best, but if your change touches rendering and you can't think of
-an automated way to verify the results, consider writing a GM test or a new page
-of SampleApp. Also, if your change is the GPU code, you may not be able to write
-it as part of the standard unit test suite, but there are GPU-specific testing
-paths you can extend.
+an automated way to verify the results, consider writing a GM test. Also, if your
+change is in the GPU code, you may not be able to write it as part of the standard
+unit test suite, but there are GPU-specific testing paths you can extend.
Submitting a patch
------------------
@@ -65,9 +64,12 @@
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`.
+Note that in order for `git cl` to work correctly, it needs to run on a clone of
+<https://skia.googlesource.com/skia>. Using clones of mirrors, including Google's mirror
+on GitHub, might lead to issues with `git cl` usage.
### Find a reviewer
@@ -78,7 +80,7 @@
### 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?-->
@@ -93,6 +95,27 @@
(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.*GTX660.*Release"
+
+For more information about testing, see [testing infrastructure](https://skia.org/dev/testing/automated_testing).
+
### Request review
Go to the supplied URL or go to the code review page and select the **Your**
@@ -104,7 +127,7 @@
_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
@@ -134,8 +157,8 @@
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
@@ -155,7 +178,7 @@
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.
@@ -171,7 +194,7 @@
[How to land Skia changes that change Blink layout test results](../chrome/layouttest)
-If you're changing the Skia API, you may need to make an associated change in Chromium.
+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](../chrome/changes)
@@ -186,26 +209,26 @@
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.
+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 his/her discretion). If so, you can mark your change as
"Abandoned", and update it with a link to the new codereview.
-### Skia committers
+### 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` 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 <email@example.com>'
~~~~
