public interface ILspPainter extends ILspPaintGroupsChangeListener
paintObjects
method is responsible for the actual painting.
The LuciadLightspeed API provides a small number of ILspPainter
implementations that allow you to customize the visualization of domain
objects. Most importantly, TLspShapePainter
can be used for all ILcdShape
objects. This painter
is flexibly customizable using the ILspStyler
and
ILspShapeDiscretizer
API.
This means that it is not recommended to implement your own
ILspPainter
extension, unless if you are certain that your particular
use case is not supported by the API. If in doubt, feel free to contact
Luciad support to verify that you need to implement your own
ILspPainter
, and to allow possible future improvements to the API to
support your use case.
paintObjects
method will typically be invoked multiple times for
each repaint of a view. Each of these calls
will receive a different TLspPaintPass
argument,
based on which the painter must choose a different subset of objects or object representations
to draw:
TLspPaintPass
for details.
In case a painter wishes to drape objects it should paint these objects when the DRAPING
or ALL
PaintDraping
mode
is passed. In addition, the painter should also request and use a terrain context from the
view. See ILspTerrainSupport
for
more details.
paintObjects
takes a Collection
of domain objects as input. This
enables the painter to perform certain optimizations, such as setting common
OpenGL state only once, or batching the data of multiple objects for more
efficient transfer to the GPU.ILspTaskExecutor
provided by the view. This implies, however, that not all objects may have
been fully processed when a paintObjects
call returns. For this
reason, the paintObjects
method returns a progress object which can be used to
indicate to the user that a view is not yet fully up-to-date.ILcdMultiKeyCache
provided by the view to cache the visual representations of objects. Note
that correct use of the cache also protects the painter against problems
that might occur if the same painter instance is used by multiple layers or
multiple views.ILcdGLDrawable
.
There are, however, a few restrictions to which painters must adhere:
ILspPainter
must indicate its minimum
requirements via the getRequiredOpenGLProfile
method. The
returned
TLspOpenGLProfile
can then be checked for compatibility with the
view in which the painter is being used.paintObjects
method is allowed to render into the
view's OpenGL context. Other methods cannot assume that an OpenGL context
is active when they are called, unless they have an ILcdGLDrawable
argument.paintObjects
method should be restored before paintObjects
returns (e.g. using
glPushAttrib
and glPopAttrib
). This rule ensures that
painters do not interfere with one another. The following exceptions apply
to this rule:
GL_BLEND
or setting glBlendFunc
).
Any painter automatically implements ILspPaintGroupsChangeListener
. Paint group
events can be used to update internal data structures without re-evaluating all the objects.
Paint group events describe changes in the list of painted objects due to various external events:
model changes, selection changes, view navigation, etc.
In addition, the paint group event mechanism can be used to provide synchronization between different painters (for example, body and label). For this, a two-phased commit cycle is used:
ILspPaintGroupsChangeListener.prepareChanges(java.util.List<com.luciad.view.lightspeed.layer.paintgroup.TLspPaintGroupsChangedEvent>, java.lang.Object, com.luciad.view.lightspeed.layer.paintgroup.ILspPaintGroupsChangeListener.Callback)
ILspPaintGroupsChangeListener.Callback.changesReady(java.lang.Object)
when readyILspPaintGroupsChangeListener.commitChanges(java.lang.Object)
It is however optional to work this way. You can simply ignore the paint group events, or apply
them immediately to your internal data structure. You must however still call
ILspPaintGroupsChangeListener.Callback.changesReady(java.lang.Object)
.
ILspPaintGroupsChangeListener.Callback
Modifier and Type | Method and Description |
---|---|
void |
addPropertyChangeListener(PropertyChangeListener aPropertyChangeListener)
Adds a
PropertyChangeListener
to the list of listeners that must be notified when
any of the properties of this ILspPainter changes. |
TLspOpenGLProfile |
getRequiredOpenGLProfile()
Returns the minimum required OpenGL profile that a view must support in
order to be compatible with this painter.
|
ILspStyler |
getStyler(TLspPaintState aPaintState)
Returns the styler used by this painter for the given
PaintState . |
TLspPaintProgress |
paintObjects(ILcdGLDrawable aGLDrawable,
List<TLspPaintGroup> aPaintGroups,
TLspPaintPass aPass,
TLspContext aContext)
Paints the specified groups of objects into a view.
|
<T> boolean |
query(List<TLspPaintGroup> aPaintGroups,
ALspPaintQuery<T> aQuery,
TLspPaintRepresentationState aPaintRepresentationState,
TLspContext aContext)
Retrieves a set of domain objects and data based on the parameters given by the query.
|
void |
registerLayer(ILspInteractivePaintableLayer aLayer,
TLspPaintRepresentation aPaintRepresentation)
Registers a layer with this painter.
|
void |
removePropertyChangeListener(PropertyChangeListener aPropertyChangeListener)
Removes a
PropertyChangeListener from the list of listeners. |
void |
unregisterLayer(ILspInteractivePaintableLayer aLayer,
TLspPaintRepresentation aPaintRepresentation)
Unregisters a layer from this painter.
|
commitChanges, prepareChanges
void registerLayer(ILspInteractivePaintableLayer aLayer, TLspPaintRepresentation aPaintRepresentation)
unregisterLayer(ILspInteractivePaintableLayer, com.luciad.view.lightspeed.layer.TLspPaintRepresentation)
.aLayer
- A layer with which this painter will be used.aPaintRepresentation
- The paint representation for which this painter will be used.void unregisterLayer(ILspInteractivePaintableLayer aLayer, TLspPaintRepresentation aPaintRepresentation)
registerLayer(ILspInteractivePaintableLayer, com.luciad.view.lightspeed.layer.TLspPaintRepresentation)
.aLayer
- A layer that needs to be unregisteredaPaintRepresentation
- The paint representation for which this painter was used with
aLayerTLspPaintProgress paintObjects(ILcdGLDrawable aGLDrawable, List<TLspPaintGroup> aPaintGroups, TLspPaintPass aPass, TLspContext aContext)
Paints the specified groups of objects into a view. The objects are partitioned into
TLspPaintGroup
s, which are created by the layer which invoked this painter.
Painters are advised to also implement ILspPaintGroupsChangeListener
,
which allows them to keep track of changes to the supplied list of paint groups. This
way, the painter can exploit temporal coherence and perform its work in the most optimal
way.
This method returns a TLspPaintProgress
which describes the completeness of the
paint operation. If the painter scheduled one or more tasks to be executed asynchronously,
it may return from its paintObjects()
method before having rendered all the objects
it was given. In this case, the returned progress object can describe the amount of work that
has been done and the work that is still remaining.
aGLDrawable
- the ILcdGLDrawable
in which the objects are to be paintedaPaintGroups
- the objects to be paintedaPass
- the current paint passaContext
- provides context information to the painterTLspPaintProgress
object describing the completeness of the paint operationTLspOpenGLProfile getRequiredOpenGLProfile()
TLspGLProfile
void addPropertyChangeListener(PropertyChangeListener aPropertyChangeListener)
PropertyChangeListener
to the list of listeners that must be notified when
any of the properties of this ILspPainter
changes.aPropertyChangeListener
- the listener that from now on will be notified of all changes
to
properties of this paintervoid removePropertyChangeListener(PropertyChangeListener aPropertyChangeListener)
PropertyChangeListener
from the list of listeners.
This listener will no longer be notified of any changes to the properties
of this ILspPainter
aPropertyChangeListener
- the listener that no longer will be notified of any changes to
properties of this painterILspStyler getStyler(TLspPaintState aPaintState)
PaintState
. Can return null
in case the painter does not use or expose a styler.aPaintState
- the paint state for which a styler is requested<T> boolean query(List<TLspPaintGroup> aPaintGroups, ALspPaintQuery<T> aQuery, TLspPaintRepresentationState aPaintRepresentationState, TLspContext aContext)
aPaintGroups
- the paint groupsaQuery
- the queryaPaintRepresentationState
- the paint representation state for which the query should be
performedaContext
- the contexttrue
if the query completed, false
if it was aborted.UnsupportedOperationException
- if the query is not supported