event/size: document size pt approximation

Fixes golang/go#13366

Change-Id: I2af5e2492450ab5b5996fa5926460b62ce9d9bf5
Reviewed-on: https://go-review.googlesource.com/24865
Reviewed-by: Nigel Tao <nigeltao@golang.org>

app/android.go

@@ -183,6 +183,16 @@ func windowConfigRead(activity *C.ANativeActivity) windowConfig {
 	density := C.AConfiguration_getDensity(aconfig)
 	C.AConfiguration_delete(aconfig)
 
+	// Calculate the screen resolution. This value is approximate. For example,
+	// a physical resolution of 200 DPI may be quantized to one of the
+	// ACONFIGURATION_DENSITY_XXX values such as 160 or 240.
+	//
+	// A more accurate DPI could possibly be calculated from
+	// https://developer.android.com/reference/android/util/DisplayMetrics.html#xdpi
+	// but this does not appear to be accessible via the NDK. In any case, the
+	// hardware might not even provide a more accurate number, as the system
+	// does not apparently use the reported value. See golang.org/issue/13366
+	// for a discussion.
 	var dpi int
 	switch density {
 	case C.ACONFIGURATION_DENSITY_DEFAULT:

event/size/size.go

@@ -20,8 +20,11 @@ type Event struct {
 	// WidthPx and HeightPx are the window's dimensions in pixels.
 	WidthPx, HeightPx int
 
-	// WidthPt and HeightPt are the window's dimensions in points (1/72 of an
-	// inch).
+	// WidthPt and HeightPt are the window's physical dimensions in points
+	// (1/72 of an inch).
+	//
+	// The values are based on PixelsPerPt and are therefore approximate, as
+	// per the comment on PixelsPerPt.
 	WidthPt, HeightPt geom.Pt
 
 	// PixelsPerPt is the window's physical resolution. It is the number of
@@ -30,6 +33,13 @@ type Event struct {
 	// There are a wide variety of pixel densities in existing phones and
 	// tablets, so apps should be written to expect various non-integer
 	// PixelsPerPt values. In general, work in geom.Pt.
+	//
+	// The value is approximate, in that the OS, drivers or hardware may report
+	// approximate or quantized values. An N x N pixel square should be roughly
+	// 1 square inch for N = int(PixelsPerPt * 72), although different square
+	// lengths (in pixels) might be closer to 1 inch in practice. Nonetheless,
+	// this PixelsPerPt value should be consistent with e.g. the ratio of
+	// WidthPx to WidthPt.
 	PixelsPerPt float32
 
 	// Orientation is the orientation of the device screen.