Add some information about coordinate systems in webrender.

This is just a start - we need to document each API that deviates from the conventions listed here, and also investigate using strongly typed units where it makes sense to.
servo · Oct 27, 2016 · 443da92 · 443da92
1 parent 4440d1d
commit 443da92
Showing 1 changed file with 22 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 # webrender
-A very incomplete proof of concept GPU renderer for Servo
+A somewhat incomplete proof of concept GPU renderer for Servo
 
 After updating shaders in webrender, go to servo and:
 
@@ -21,3 +21,24 @@ To use a custom webrender with servo, go to your servo build directory and:
 ```
 
   * Build as normal
+
+# Webrender coordinate systems.
+
+The general rule of thumb is that coordinates used in display
+lists, clips, viewports, transforms and stacking contexts are always:
+
+ * CSS / Logical pixels.
+ * In the local (untransformed) coordinate space of the owning stacking context.
+ * Assume that the scroll offset is zero.
+
+The coordinates used in stacking contexts and display lists are logical
+units, the same as CSS pixels. They are the same value regardless of the
+dpi scaling ratio. The DPI scaling ratio is applied on the GPU as required.
+
+When scrolling occurs, none of the coordinates in the display lists change.
+Scrolling is handled internally by tweaking matrices that get sent to the
+GPU in order to transform the display items.
+
+There are a small number of APIs (primarily ones that interact with events
+such as scroll and mouse clicks etc) that use device pixels (including any
+hi-dpi scale factor).