From be23e48e7f11a806eef043313606d62856abeb40 Mon Sep 17 00:00:00 2001
From: Paul Davis <paul@linuxaudiosystems.com>
Date: Mon, 15 Apr 2013 22:34:36 -0400
Subject: [PATCH] add some comments to Canvas::Image and ensure that the canvas
 redraws after a put_image() call is handled in the GUI thread

---
 libs/canvas/canvas/image.h | 21 +++++++++++++++++++++
 libs/canvas/image.cc       |  9 +++++++++
 2 files changed, 30 insertions(+)

diff --git a/libs/canvas/canvas/image.h b/libs/canvas/canvas/image.h
index b4227ac09d..a3b1a269ba 100644
--- a/libs/canvas/canvas/image.h
+++ b/libs/canvas/canvas/image.h
@@ -48,7 +48,28 @@ public:
 	Cairo::Format format;
     };
 
+    /** 
+     * Returns a shared_ptr to a Data object that can be used to 
+     * write image data to. The Data object will contain a pointer
+     * to the buffer, along with image properties that may be
+     * useful during the data writing.
+     * 
+     * Can be called from any thread BUT ..
+     *
+     * ... to avoid collisions with Image deletion, some synchronization method
+     * may be required or the use of shared_ptr<Image> or similar.
+     */
     boost::shared_ptr<Data> get_image ();
+
+    /**
+     * Queues a Data object to be used to redraw this Image item
+     * at the earliest possible opportunity.
+     *
+     * May be called from any thread BUT ...
+     *
+     * ... to avoid collisions with Image deletion, some synchronization method
+     * may be required or the use of shared_ptr<Image> or similar.
+     */
     void put_image (boost::shared_ptr<Data>);
 
     void render (Rect const &, Cairo::RefPtr<Cairo::Context>) const;
diff --git a/libs/canvas/image.cc b/libs/canvas/image.cc
index 22ef042cfb..26bc35eb37 100644
--- a/libs/canvas/image.cc
+++ b/libs/canvas/image.cc
@@ -60,6 +60,8 @@ Image::compute_bounding_box () const
 boost::shared_ptr<Image::Data>
 Image::get_image ()
 {
+	/* can be called by any thread */
+
 	int stride = Cairo::ImageSurface::format_stride_for_width (_format, _width);
 	boost::shared_ptr<Data> d (new Data (boost::shared_array<uint8_t> (new uint8_t[stride*_height]), _width, _height, stride, _format));
 
@@ -69,6 +71,8 @@ Image::get_image ()
 void
 Image::put_image (boost::shared_ptr<Data> d)
 {
+	/* can be called by any thread */
+
 	_pending = d;
 	DataReady (); /* EMIT SIGNAL */
 }
@@ -77,8 +81,13 @@ void
 Image::accept_data () 
 {
 	/* must be executed in gui thread */
+
+	begin_change ();
+
 	_current = _pending;
 	_pending.reset ();
 	_need_render = true;
+
+	end_change (); // notify canvas that we need redrawing
 }