Kartikaya Gupta (email:kats@mozilla.staktrace.com) Assignee
	Description • 10 years ago

      No description provided.

	Kartikaya Gupta (email:kats@mozilla.staktrace.com) Assignee
	Comment 1 • 10 years ago

Writing docs is hard. URL to what I have so far, if anybody has early feedback.

	Milan Sreckovic [:milan] (needinfo for best results)
	Comment 2 • 10 years ago

I like it.  One question - it seems that it would be useful to have the "usability" goals in there, and you're already mentioning some in very broad terms ("track the finger".)  It would be nice to have that information, and more of it, as it informs the design and implementation; I don't know if some of this already exists in some UX documents, in which case we can just link to it.

	Kartikaya Gupta (email:kats@mozilla.staktrace.com) Assignee
	Comment 3 • 10 years ago

I seem to have stalled on this so I'd like to get what I have so far landed at least. We can continue updating it as we go forward.

	Kartikaya Gupta (email:kats@mozilla.staktrace.com) Assignee
	Comment 4 • 10 years ago

You can view the image in the patch at https://github.com/staktrace/gecko-dev/blob/docs/gfx/doc/AsyncPanZoom-HighLevel.png

	Botond Ballo [:botond]
	Comment 5 • 10 years ago

Comment on attachment 8464744 [details] [diff] [review]
Patch

Review of attachment 8464744 [details] [diff] [review]:
-----------------------------------------------------------------

::: gfx/doc/AsyncPanZoom.md
@@ +64,5 @@
> +The painted content stored in the shadow layers will only represent some subset of the page, because it would require an unbounded amount of memory to store the entire page (which can be arbitarily long).
> +If the subset of the page stored in the shadow layers is limited to only what is visible on-screen, then as soon as the user pans, there will be some unpainted area of the page exposed.
> +This unpainted area is referred to as "checkerboarding", and we try to avoid it where possible.
> +A good way to avoid it is to have the shadow layers contain a region larger than what is visible, but not so large that it is a huge drain on memory.
> +The region of a layer that is painted and stored in the shadow layer is called the "displayport".

I would reorganize this paragraph along the following lines: 

  - The region of a layer that is painted is called the 'displayport'. We choose how large to make it.
  - We make it larger than the what is visible on-screen because ...
  - We can't always make it the whole page because ...
  - If the user pans outside of the displayport (before the main thread gets around to painting a new displayport) the user sees ... which is called 'checkerboarding'.

@@ +69,5 @@
> +
> +There are many possible ways to determine what the displayport should be in order to balance the tradeoffs involved (i.e. having one that is too big is bad for memory usage, and having one that is too small results in excessive checkerboarding).
> +Ideally, the displayport should cover exactly the area that we know the user will make visible.
> +Although we cannot know this for sure, we can use heuristics based on current panning velocity and direction to ensure a reasonably-chosen displayport area.
> +This calculation is done in the APZ code, and a new desired displayport is frequently sent to the main thread as the user is panning around.

s / "a new desired displayport"/ "a new desired displayport size" or "instructions to paint a new displayport"

@@ +75,5 @@
> +### Multiple layers
> +
> +Consider, for example, a scrollable page that contains an iframe which itself is scrollable.
> +The iframe can be scrolled independently of the top-level page, and we would like both the page and the iframe to scroll responsively.
> +This means that we need two APZ things - one that tracks the scrolling of the top-level page, and one that tracks the iframe.

s / "This means that we need two APZ things ... " / "This means that we want asynchronous panning and zooming for both the top-level page and the iframe"

@@ +78,5 @@
> +The iframe can be scrolled independently of the top-level page, and we would like both the page and the iframe to scroll responsively.
> +This means that we need two APZ things - one that tracks the scrolling of the top-level page, and one that tracks the iframe.
> +In the general case, the layers are arranged in a tree structure, and so within the APZ code we have a matching tree of AsyncPanZoomController (APZC) objects, one for each scrollable layer.
> +To manage this tree of APZC instances, we have a single APZCTreeManager object.
> +Each APZC is relatively independent and handles the scrolling for its associated layer, but there are some cases in which they need to interact; these cases are described in the sections below.

We should mention somewhere in this paragraph what kind of web content gets a scrollable layer: documents (whether the root document, or a sub-document in an <iframe>), and overflow:scroll elements (typically <div>s).

@@ +87,5 @@
> +As described above, we will have two APZC instances - one for the page and one for the iframe.
> +When the user puts their finger down on the screen and moves it, we need to do some sort of hit detection in order to determine whether their finger is on the iframe or on the top-level page.
> +Based on where their finger lands, the appropriate APZC instance needs to handle the input.
> +This hit detection is also done in the APZCTreeManager, as it has the necessary information about the sizes and positions of the layers.
> +Currently this hit detection is not perfect, as it uses rects and does not account for things like rounded corners and opacity.

Maybe mention pinches as well.

@@ +101,5 @@
> +
> +### Input event untransformation
> +
> +The APZC architecture by definition results in two copies of a "scroll position" for each scrollable layer.
> +There is the original copy on the main thread that is accessible to web content and the rest of the layout and painting code.

s/the rest of the//

	Kartikaya Gupta (email:kats@mozilla.staktrace.com) Assignee
	Comment 6 • 10 years ago

Made the suggested changes and landed:

https://hg.mozilla.org/integration/mozilla-inbound/rev/8506e07e2541

	Ryan VanderMeulen [:RyanVM]
	Comment 7 • 10 years ago

https://hg.mozilla.org/mozilla-central/rev/8506e07e2541