compositor: note, weston_surface_damage does it wrong

The fix is not trivial, so I want to document the problem before I
forget about it again.

Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>

src/compositor.c

@@ -1357,6 +1357,16 @@ weston_view_schedule_repaint(struct weston_view *view)
 			weston_output_schedule_repaint(output);
 }
 
+/**
+ * XXX: This function does it the wrong way.
+ * surface->damage is the damage from the client, and causes
+ * surface_flush_damage() to copy pixels. No window management action can
+ * cause damage to the client-provided content, warranting re-upload!
+ *
+ * Instead of surface->damage, this function should record the damage
+ * with all the views for this surface to avoid extraneous texture
+ * uploads.
+ */
 WL_EXPORT void
 weston_surface_damage(struct weston_surface *surface)
 {

src/compositor.h

@@ -871,7 +871,10 @@ struct weston_surface {
 	struct wl_resource *resource;
 	struct wl_signal destroy_signal;
 	struct weston_compositor *compositor;
+
+	/** Damage in local coordinates from the client, for tex upload. */
 	pixman_region32_t damage;
+
 	pixman_region32_t opaque;        /* part of geometry, see below */
 	pixman_region32_t input;
 	int32_t width, height;