Asynchronous painting in a GXY view

LuciadLightspeed provides support for asynchronous painting at the layer level. Selected layers or groups of layers can be painted in buffer images in different threads. If some buffer images are not up to date yet, a best effort is made to provide previews of their contents. The view is updated automatically whenever the final buffer images are ready.

The support for asynchronous painting is based on a wrapper for a standard ILcdGXYLayer. Whenever a layer is created for which the painting could be slow, the code can create an asynchronous wrapper, as shown in Program: Creating an asynchronous layer for a slow layer. The wrapper can then be added to the view like any other layer.

Once you wrap a layer for asynchronous painting, the asynchronous painting thread can access the original layer anytime. It is thus unsafe to access the original layer (including its painters and label painters) from any other thread, unless you take specific precautions. The layer wrapper itself can be accessed from the event dispatch thread. Accessing asynchronously painted layers provides more information on how to access your original layer after it has been wrapped. See Threading and locking in LuciadLightspeed for a more general overview of the concurrency best practices in LuciadLightspeed.

LuciadLightspeed offers the following asynchronous layer wrapper implementations:

The interface ILcdGXYAsynchronousLayerWrapper provides access to the standard properties of ILcdGXYLayer, which can be safely read and written from the Event Dispatch Thread (EDT). It also provides standard methods like getBounds and applyOnInteract. In the default implementation, these methods delegate to the wrapped layer. To ensure thread-safety, they will block if the layer is being painted in the painting thread.

The layer interface ILcdGXYLayer also provides access to the painter and label painter for any given object. The default implementation of the asynchronous layer wrapper returns a clone of the painter returned by the inner layer. It blocks if the layer is being painted in the painting thread, in order to safely create the clone. The clone can then be used safely, assuming the painter class provides a sufficiently deep clone. If you use your own painters, you can use ILcdDeepCloneable to handle recursive cloning loops.

If an application wants to access the wrapped layer directly, the simplest way is to retrieve it from the layer wrapper, with getGXYLayer. It can then, for example, read the layer’s properties. It is, however, not safe to modify the layer properties this way. Or more generally, it is not safe to invoke methods that are not thread-safe, since the layer may be painted in the painting thread of a paint queue.

A safe way to retrieve and to modify non-standard layer properties is to ask the layer wrapper to execute the modification code at a safe point in time, on an appropriate thread. The interface ILcdGXYAsynchronousLayerWrapper provides the methods invokeAndWaitOnGXYLayer, invokeLaterOnGXYLayer, invokeLaterOnGXYLayerInEDT and invokeNowOnGXYLayer for this purpose:

Providing transparent access to a custom layer interface explains another, more advanced alternative to accessing the wrapped layer’s functionality: extending the layer wrapper.

When editing the model of a wrapped layer you need to do this in a thread-safe way since the model is being painted in a separate painting thread. The layer wrapper and the paint queue guard any read access by means of read locks on the model, as described in Accessing asynchronously painted layers. Any code that modifies the model or its elements therefore has to make sure that it obtains a write lock on the model, as shown in Threading and locking in LuciadLightspeed.

Since each image buffer has the same size as the view, the required amount of memory can be considerable. It can therefore be useful to share paint queues between asynchronous layer wrappers. The contents of the actual layers are then painted in the same threads and in the same image buffers. Shared paint queues also reduce view repaints for the compositing created images, which can be important when the view contains slow, synchronously painted layers.

On the downside, sharing a paint queue implies that view repaints are as slow as the combined repaints of the layers. Layers that share a paint queue must also be consecutive. Otherwise their image buffers cannot be composited properly in the view. Customizing paint queue assignments explains how to simplify the non-trivial task of assigning paint threads and buffers to asynchronously painted layers by using a paint queue manager.

A paint queue also has a flag to determine whether it should create image buffers for all painting modes or not. It is possible to reduce the number of buffers in order to reduce the memory usage. Depending on the type of layer, this comes at the cost of some performance or quality. By default, the value EVERYTHING is specified. The paint queue then creates image buffers for all painting modes. The value BODIES_AND_SKIP instructs the paint queue to only create an image buffer for painting the bodies of the model elements. The labels and selection are painted synchronously, but only when the image buffer is ready. To avoid the continuous appearing and disappearing of the labels and selection in this mode, a minimum waiting delay can be specified using setSkipDelay.

An asynchronous layer wrapper always needs a paint queue, which manages one or more image buffers and a painting thread. The paint queue maintains an image buffer for each painting mode (bodies, labels, selection, and so on). It keeps the images updated in its painting thread. In the event dispatch thread (AWT thread, Swing thread), it can then composite the created images, interleaving them with other layers, respecting the proper painting order.

A paint queue manager greatly simplifies the non-trivial task of assigning paint threads and buffers to asynchronously painted layers. All view implementations that support asynchronous painting configure a paint queue manager out of the box.

LuciadLightspeed offers two ways to customize a paint queue manager. The easiest way is to create and set up the default paint queue manager, TLcdGXYAsynchronousPaintQueueManager, with a custom paint hint provider. Paint hints are a powerful way to specify how to paint a layer and whether or not the layer can share a paint queue with its neighboring layers. If you want more flexibility, you can choose to directly subclass ALcdGXYAsynchronousPaintQueueManager, and manage the assignments yourself.

If your application contains an extension of ILcdGXYLayer, and you do not want to use a blocking method to change its non-standard properties, you can extend the layer wrapper to implement your ILcdGXYLayer extension. The layer wrapper can then offer the same additional properties in its interface. To do this, the layer wrapper extension must provide an implementation of ILcdGXYLayerChangeTracker which ensures that the additional properties remain consistent between the layer wrapper and the wrapped layer.

The asynchronous layer wrapper isolates the wrapped layer from the outside world. This way, the program can change properties on the layer wrapper at any time in one thread, for example the Event Dispatch Thread (EDT). At the same time, the paint queue paints the wrapped layer in its painting thread. Neither thread has to wait for the other one. The paint queue synchronizes the properties of the layer wrapper and the properties of the wrapped layer at the appropriate and safe points in time.

The default implementation of ILcdGXYAsynchronousLayerWrapper, TLcdGXYAsynchronousLayerWrapper, wraps basic implementations of ILcdGXYLayer, like TLcdGXYLayer. The synchronization of properties between the layer wrapper and the wrapped layer is the responsibility of implementations of ILcdGXYLayerChangeTracker.

Figure 4, “Using an ILcdGXYLayerChangeTracker” shows a sequence diagram of this mechanism. The paint method of the paint queue first propagates any changes from the layer wrapper to the wrapped layer. It then queues the actual painting operation on the painting thread, so it can return right away. Note that the paint queue can be asked to wait a while for the asynchronous painting to complete, so that the results are painted immediately. This behavior is set using the method setSynchronousDelay. After the painting operation is queued, the wrapped layer is painted in an image buffer in the painting thread. When the painting is done, any changes (for example, label positions) are propagated from the wrapped layer back to the layer wrapper. Finally, the paint queue invalidates the view, so the newly created image can be blitted to the view on the next repaint.

The class TLcdGXYAsynchronousLayerWrapper provides an implementation that keeps the basic layer properties consistent.

An example of an asynchronous layer wrapper providing transparent access to another layer interface is TLcdGXYAsynchronousEditableLabelsLayerWrapper, which can wrap implementations of ILcdGXYEditableLabelsLayer. In addition to the basic layer properties, it also manages the synchronization of the label positions, from the wrapper layer to the layer with editable layers, but also the other way round, whenever the label painter has updated the label positions.

Developing and debugging multi-threaded applications can be difficult and error-prone. This list of pointers and tips help you deal with possible trouble during the use and extension of the asynchronous painting API: