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

@@ -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;

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
 }