public abstract class ALspViewXYZWorldTransformation extends Object implements Cloneable, ILcdPropertyChangeSource
apply
method in
this interface is used to this effect.
ALspViewXYZWorldTransformation
determines whether that view is a 2D or 3D view.
All layers and painters in a view are expected to cope with both scenarios, as well as with
runtime switches between the two. Hence, for many application developers the distinction between
2D and 3D should pose no special concern. Implementations of custom layers and/or painters,
however,
may wish to check the type of the world-to-view transformation if they need separate code paths
for 2D and 3D rendering.
The class TLspViewTransformationUtil
provides
convenience methods for switching a view between 2D and 3D. These methods not only instantiate
the appropriate ALspViewXYZWorldTransformation
, but also initialize it with sensible
default parameters.
TLcdMapScale
for more information.
Lightspeed views support high DPI rendering, meaning that map features such as icons, line widths or
font sizes will be scaled up in response to the DPI scale settings of the host operating system.
This is largely transparent to the user, but some caveats apply when using the methods of this
class to transform back and forth between pixel and world coordinates.
When using a DPI scale factor other than 100%, the Java runtime environment essentially creates
an additional coordinate system. Let us refer to this system as "toolkit coordinates". Toolkit
coordinates correspond to screen pixels that have been scaled by the DPI scaling factor. If the
DPI scale is 150%, for instance, then toolkit == screen / 1.5
(for both the X and Y axes). All
UI components (both in Swing/AWT and JavaFX) will express their dimensions and locations in
toolkit coordinates. This means that the width and height reported by, for instance, a
JPanel
will be smaller than the panel's size in actual screen pixels.
Lightspeed views will render themselves at full screen resolution, but will use larger icons,
fonts, and so on, proportional to the DPI scale factor. The dimensions of a view in toolkit
coordinates are simply those reported by the view's host
component
-- the view itself, as well as its ALspViewXYZWorldTransformation
, will
always report the actual screen pixel size of the view. The ratio between these two sizes
is equal to the DPI scale factor.
This class provides two-way transformation methods between toolkit, view and world
coordinates. API users should take care to call the appropriate method for the task at
hand. The most common scenario will be to transform between toolkit and world
coordinates -- the intermediate view coordinates should only be needed in very advanced
use cases such as when implementing a custom
painter
.
A final note about toolkit coordinates is that, unlike view coordinates, they do not have
a third dimension. When transforming between toolkit and view coordinates, therefore, Z is
assumed to be zero. This is reflected in method signatures by using java.awt.Point
instead of ILcdPoint
as the parameter type in places where Z is ignored.
All the above applies both to AWT/Swing and to JavaFX. High DPI rendering can be
overridden using the following system properties:
-Dsun.java2d.uiScale=1.0
for AWT/Swing (1.0 corresponds to 100%)-Dglass.win.uiScale=100%
for JavaFXimmutable clone
can be obtained
to be used for asynchronous tasks.Modifier and Type | Class and Description |
---|---|
static class |
ALspViewXYZWorldTransformation.LocationMode
Enumeration of modes supported by
viewPoint2WorldSFCT() and
toolkitPoint2WorldSFCT() . |
static class |
ALspViewXYZWorldTransformation.OutputDevice
Enumeration of devices to which a view can be rendered.
|
Modifier and Type | Method and Description |
---|---|
abstract void |
apply(ILcdGLDrawable aGLDrawable)
Applies the current world-to-view transformation to the specified
ILcdGLDrawable . |
abstract void |
applyLocalOrigin(ILcdGLDrawable aGLDrawable,
ILcdPoint aOrigin)
Modifies the OpenGL
MODELVIEW matrix so that the given
point is the origin. |
ALspViewXYZWorldTransformation |
clone()
Returns a deep clone of this transformation.
|
Rectangle2D |
getClip()
Returns the clipping rectangle which identifies the portion of the view that is currently
being rendered.
|
double |
getFeatureScale()
Returns a scale factor which changes the relative size of features (such
as icons, labels or line widths) in a view.
|
abstract TLspFrustum |
getFrustum()
Returns the current view frustum.
|
abstract ILcdComplexPolygon |
getGeodeticVisibleArea()
Returns a polygon which approximates the area of the globe which is
visible in the current view.
|
abstract int |
getHeight()
Returns the height of the viewport in pixels.
|
abstract Object |
getIdentifier()
Returns an identifier object that can be used to efficiently
compare transformations.
|
abstract ALspViewXYZWorldTransformation |
getImmutableClone()
Returns an immutable deep clone of this transformation
|
TLcdMapScale |
getMapScale(TLcdMapScale.ScaleLocation aScaleLocation)
Returns the unitless map scale ratio for which to paint the view contents.
|
ALspViewXYZWorldTransformation.OutputDevice |
getOutputDevice()
Returns the type of output device to which a view is being rendered.
|
double |
getScale()
Returns the scale for which to paint objects.
|
abstract double |
getScaleX()
Returns the horizontal scale for which to paint objects.
|
abstract double |
getScaleY()
Returns the vertical scale for which to paint objects.
|
ILspView |
getView()
Returns the registered view, or null if no view was registered.
|
abstract int |
getWidth()
Returns the width of the viewport in pixels.
|
abstract void |
restoreLocalOrigin(ILcdGLDrawable aGLDrawable)
Undoes a previously applied local coordinate origin.
|
abstract void |
set(ALspViewXYZWorldTransformation aOther)
Sets this view transformation's properties to be equal to the other one.
|
abstract void |
setSize(int aWidth,
int aHeight)
Sets the size of the viewport.
|
void |
toolkitPoint2ViewSFCT(Point aToolkitPoint,
ILcd3DEditablePoint aViewPointSFCT)
Transforms a point from toolkit coordinates to view coordinates.
|
void |
toolkitPoint2WorldSFCT(Point aToolkitPoint,
ALspViewXYZWorldTransformation.LocationMode aLocationMode,
ILcd3DEditablePoint aWorldPointSFCT)
Returns the location, in world coordinates, of the point currently
located under
aViewPoint , with the latter being a point in
toolkit coordinates. |
void |
toolkitPoint2WorldSFCT(Point aToolkitPoint,
ILcd3DEditablePoint aWorldPointSFCT)
Transforms a point from toolkit coordinates to world coordinates.
|
void |
viewAWTPoint2worldSFCT(Point aViewPoint,
ALspViewXYZWorldTransformation.LocationMode aLocationMode,
ILcd3DEditablePoint aWorldPointSFCT)
|
void |
viewBounds2worldSFCT(ILcdBounds aViewBounds,
ILcd3DEditableBounds aWorldBoundsSFCT)
Transforms a bounds in view coordinates to a bounds in world coordinates.
|
void |
viewPoint2ToolkitSFCT(ILcdPoint aViewPoint,
Point aToolkitPointSFCT)
Transforms a point from view coordinates to toolkit coordinates.
|
abstract void |
viewPoint2WorldSFCT(ILcdPoint aViewPoint,
ILcd3DEditablePoint aWorldPointSFCT)
Transforms a point in view coordinates to a point in world coordinates.
|
void |
viewPoint2WorldSFCT(Point aViewPoint,
ALspViewXYZWorldTransformation.LocationMode aLocationMode,
ILcd3DEditablePoint aWorldPointSFCT)
Returns the location, in world coordinates, of the point currently
located under
aViewPoint , with the latter being a point in
view coordinates. |
void |
worldBounds2viewSFCT(ILcdBounds aWorldBounds,
ILcd3DEditableBounds aViewBoundsSFCT)
Transforms a bounds in world coordinates to a bounds in view coordinates.
|
void |
worldPoint2ToolkitSFCT(ILcdPoint aWorldPoint,
Point aToolkitPointSFCT)
Transforms a point from world coordinates to toolkit coordinates.
|
abstract void |
worldPoint2ViewSFCT(ILcdPoint aWorldPoint,
ILcd3DEditablePoint aViewPointSFCT)
Transforms a point in world coordinates to a point in view coordinates.
|
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
addPropertyChangeListener, removePropertyChangeListener
public ILspView getView()
public abstract void apply(ILcdGLDrawable aGLDrawable)
ILcdGLDrawable
. This method sets the OpenGL modelview and projection
matrices as appropriate.aGLDrawable
- the ILcdGLDrawable
to be configuredpublic abstract void applyLocalOrigin(ILcdGLDrawable aGLDrawable, ILcdPoint aOrigin)
MODELVIEW
matrix so that the given
point is the origin.
This method does not modify this transformation object.aGLDrawable
- the drawable that is painted on. Shall not be null.aOrigin
- the new origin. Shall not be null.public abstract void restoreLocalOrigin(ILcdGLDrawable aGLDrawable)
aGLDrawable
- the access point to OpenGLpublic abstract void set(ALspViewXYZWorldTransformation aOther)
aOther
- the transformation to copy the properties fromIllegalArgumentException
- if aOther is not a compatible transformation (i.e., when trying
to set the properties of a 3D transformation to a 2D transformation and vice versa)TLspViewXYZWorldTransformation2D.set(ALspViewXYZWorldTransformation)
,
TLspViewXYZWorldTransformation3D.set(ALspViewXYZWorldTransformation)
public abstract TLspFrustum getFrustum()
public abstract void worldPoint2ViewSFCT(ILcdPoint aWorldPoint, ILcd3DEditablePoint aViewPointSFCT)
See the class documentation for important information about view coordinates and DPI scaling.
aWorldPoint
- the world point to transformaViewPointSFCT
- the point to be setNullPointerException
- if either parameter is nullpublic abstract void viewPoint2WorldSFCT(ILcdPoint aViewPoint, ILcd3DEditablePoint aWorldPointSFCT)
Transforms a point in view coordinates to a point in world coordinates. The result of the transformation is stored in the second point parameter.
Note: this method interprets the z value ([0,1]) of the given point as the depth value
in view space. If you are using 2D view points (e.g. the x and y coordinates of the mouse), it
is advised to use viewPoint2WorldSFCT(Point, LocationMode, ILcd3DEditablePoint)
, which can calculate
the world point at sea level or on the surface closest to the viewer.
See the class documentation for important information about view coordinates and DPI scaling.
aViewPoint
- the view point to transform to world coordinatesaWorldPointSFCT
- the point to setNullPointerException
- if either parameter is nullpublic void worldBounds2viewSFCT(ILcdBounds aWorldBounds, ILcd3DEditableBounds aViewBoundsSFCT)
See the class documentation for important information about view coordinates and DPI scaling.
aWorldBounds
- the world bounds to transformaViewBoundsSFCT
- the bounds to be setNullPointerException
- if either parameter is nullpublic void viewBounds2worldSFCT(ILcdBounds aViewBounds, ILcd3DEditableBounds aWorldBoundsSFCT)
See the class documentation for important information about view coordinates and DPI scaling.
aViewBounds
- the view bounds to transformaWorldBoundsSFCT
- the bounds to be setNullPointerException
- if either parameter is nullpublic abstract void setSize(int aWidth, int aHeight)
aWidth
- the new width of the viewportaHeight
- the new height of the viewportpublic abstract int getWidth()
public abstract int getHeight()
public ALspViewXYZWorldTransformation clone()
public abstract ALspViewXYZWorldTransformation getImmutableClone()
Use this clone for example to pass the view-to-world transformation to another thread than the painting thread.
public abstract Object getIdentifier()
Object yourIdentifier = ...;
ALspViewXYZWorldTransformation v2w = ...;
Object myIdentifier = v2w.getIdentifier();
boolean transformationValid = yourIdentifier.equals(myIdentifier);
public double getScale()
ILcdXYWorldReference
of the registered view. For example, a view displaying
geographical data could use a scale in pixels per meter.
If you need to calculate the scale with respect to toolkit coordinates, divide this value by the
dpi scale
.
public TLcdMapScale getMapScale(TLcdMapScale.ScaleLocation aScaleLocation)
TLspViewNavigationUtil.zoom(TLcdMapScale, TLcdMapScale.ScaleLocation)
,
TLcdMapScale
,
ILspLayer.getMapScaleProvider()
public abstract double getScaleX()
ILcdXYWorldReference
of the registered view. For example, a view displaying
geographical data could use a scale in pixels per meter.public abstract double getScaleY()
ILcdXYWorldReference
of the registered view. For example, a view displaying
geographical data could use a scale in pixels per meter.public void viewAWTPoint2worldSFCT(Point aViewPoint, ALspViewXYZWorldTransformation.LocationMode aLocationMode, ILcd3DEditablePoint aWorldPointSFCT) throws TLcdOutOfBoundsException
viewPoint2WorldSFCT(Point, LocationMode, ILcd3DEditablePoint)
or toolkitPoint2WorldSFCT(Point, LocationMode, ILcd3DEditablePoint)
instead.TLcdOutOfBoundsException
public double getFeatureScale()
public Rectangle2D getClip()
null
.public ALspViewXYZWorldTransformation.OutputDevice getOutputDevice()
getClip()
and getFeatureScale()
properties of this transformation
should be taken into account where appropriate.OutputDevice
public abstract ILcdComplexPolygon getGeodeticVisibleArea()
null
.public void toolkitPoint2ViewSFCT(Point aToolkitPoint, ILcd3DEditablePoint aViewPointSFCT)
Transforms a point from toolkit coordinates to view coordinates. The
result is stored in the aViewPointSFCT
parameter. The Z coordinate
of the output is always set to zero.
See the class documentation for important information about view coordinates and DPI scaling.
aToolkitPoint
- a point in toolkit coordinatesaViewPointSFCT
- will be set to the corresponding point in view coordinatespublic void toolkitPoint2WorldSFCT(Point aToolkitPoint, ILcd3DEditablePoint aWorldPointSFCT)
Transforms a point from toolkit coordinates to world coordinates. This is equivalent
to transforming from toolkit to view and then from view to world coordinates. The result
is stored in the aWorldPointSFCT
parameter. The Z coordinate of the input is
assumed to be zero, therefore the output point is always located on the near plane.
See the class documentation for important information about view coordinates and DPI scaling.
aToolkitPoint
- a point in toolkit coordinatesaWorldPointSFCT
- will be set to the corresponding point in world coordinatespublic void viewPoint2ToolkitSFCT(ILcdPoint aViewPoint, Point aToolkitPointSFCT)
Transforms a point from view coordinates to toolkit coordinates. The result is
stored in the aToolkitPointSFCT
parameter. The Z coordinate of the input
is discarded.
See the class documentation for important information about view coordinates and DPI scaling.
aViewPoint
- a point in view coordinatesaToolkitPointSFCT
- will be set to the corresponding point in toolkit coordinatespublic void worldPoint2ToolkitSFCT(ILcdPoint aWorldPoint, Point aToolkitPointSFCT)
Transforms a point from world coordinates to toolkit coordinates. This is equivalent to
transforming from world to view and then from view to toolkit coordinates. The result is
stored in the aToolkitPointSFCT
parameter. The Z coordinate of the intermediate
view point is discarded.
See the class documentation for important information about view coordinates and DPI scaling.
aWorldPoint
- a point in world coordinatesaToolkitPointSFCT
- will be set to the corresponding point in toolkit coordinatespublic void viewPoint2WorldSFCT(Point aViewPoint, ALspViewXYZWorldTransformation.LocationMode aLocationMode, ILcd3DEditablePoint aWorldPointSFCT) throws TLcdOutOfBoundsException
Returns the location, in world coordinates, of the point currently
located under aViewPoint
, with the latter being a point in
view coordinates.
aLocationMode
indicates whether the returned point should be
at sea level or on the surface closest to the viewer. The Z coordinate of the
view point is therefore irrelevant. Hence, this method accepts a java.awt.Point
rather than an ILcdPoint
.
See the class documentation for important information about view coordinates and DPI scaling.
aViewPoint
- X and Y view coordinates of the point of which the location should be
determinedaLocationMode
- specifies how the location should be determinedaWorldPointSFCT
- receives the world coordinates corresponding to aViewPointTLcdOutOfBoundsException
- if aViewPoint is not over the surface of the Earth in the current viewALspViewXYZWorldTransformation.LocationMode
public void toolkitPoint2WorldSFCT(Point aToolkitPoint, ALspViewXYZWorldTransformation.LocationMode aLocationMode, ILcd3DEditablePoint aWorldPointSFCT) throws TLcdOutOfBoundsException
Returns the location, in world coordinates, of the point currently
located under aViewPoint
, with the latter being a point in
toolkit coordinates.
aLocationMode
indicates whether the returned point should be
at sea level or on the surface closest to the viewer.
See the class documentation for important information about view coordinates and DPI scaling.
aToolkitPoint
- toolkit coordinates of the point of which the location should be
determinedaLocationMode
- specifies how the location should be determinedaWorldPointSFCT
- receives the world coordinates corresponding to aViewPointTLcdOutOfBoundsException
- if aToolkitPoint is not over the surface of the Earth in the current viewALspViewXYZWorldTransformation.LocationMode