Package com.luciad.view.lightspeed

Class TLspViewBuilder

java.lang.Object
com.luciad.view.lightspeed.TLspViewBuilder
public class TLspViewBuilder extends Object
Builder for creating ILspView instances. This builder has methods to set a number of common view properties, as well as "build" methods for the different available types of view (buildAWTView(), buildSwingView(), buildOffscreenView()) and buildStereoscopicView(TLspStereoscopicDevice).
Since:
2012.0

  • Method Details

    • newBuilder

      public static TLspViewBuilder newBuilder()
      Creates a new view builder with default settings.
      Returns:
      a new view builder

    • buildAWTView

      public TLspAWTView buildAWTView() throws UnsatisfiedLinkError
      Creates a TLspAWTView with the current settings of this builder.
      Returns:
      a new AWT view
      Throws:
      UnsatisfiedLinkError - if the OpenGL native libraries cannot be found

    • buildStereoscopicView

      public ILspView buildStereoscopicView(TLspStereoscopicDevice aStereoscopicDevice) throws UnsatisfiedLinkError
      Creates a ILspView with the current settings of this builder. Depending on the device some parameters may be ignored.
      Parameters:
      aStereoscopicDevice - the device for which this view will be used.
      Returns:
      a new stereoscopic view
      Throws:
      UnsatisfiedLinkError - if the OpenGL native libraries cannot be found
      Since:
      2016.0

    • buildOffscreenView

      public TLspOffscreenView buildOffscreenView() throws UnsatisfiedLinkError

      Creates a TLspOffscreenView with the current settings of this builder.

      Note that automatic context sharing is not enabled for offscreen views.

      Returns:
      a new offscreen view
      Throws:
      UnsatisfiedLinkError - if the OpenGL native libraries cannot be found

    • buildSwingView

      public TLspSwingView buildSwingView() throws UnsatisfiedLinkError
      Creates a TLspSwingView with the current settings of this builder.
      Returns:
      a new Swing view
      Throws:
      UnsatisfiedLinkError - if the OpenGL native libraries cannot be found
      Since:
      2012.1.05

    • buildFXView

      public TLspFXView buildFXView() throws UnsatisfiedLinkError
      Creates a TLspFXView with the current settings of this builder.
      Returns:
      a new JavaFX view
      Throws:
      UnsatisfiedLinkError - if the OpenGL native libraries cannot be found
      Since:
      2019.0

    • buildExternalView

      public TLspExternalView buildExternalView() throws UnsatisfiedLinkError
      Creates a Lightspeed view that renders into an externally created OpenGL context with the current settings of this builder.
      Returns:
      a new external view
      Throws:
      UnsatisfiedLinkError - if the OpenGL native libraries cannot be found
      Since:
      2017.0

    • buildExternalStereoscopicView

      public TLspExternalView buildExternalStereoscopicView(TLspStereoscopicDevice aStereoscopicDevice) throws UnsatisfiedLinkError
      Creates a stereoscopic Lightspeed view that renders into an externally created OpenGL context with the current settings of this builder.
      Returns:
      a new external view
      Throws:
      UnsatisfiedLinkError - if the OpenGL native libraries cannot be found
      Since:
      2017.0

    • size

      public TLspViewBuilder size(int aWidth, int aHeight)
      Sets the initial size of the view. The default size is 640x480 pixels.
      Parameters:
      aWidth - the width of the view in pixels
      aHeight - the height of the view in pixels
      Returns:
      this builder

    • background

      public TLspViewBuilder background(Color aColor)
      Sets the background color of the view. The default is sea blue.
      Parameters:
      aColor - the background color
      Returns:
      this builder
      Since:
      2013.0

    • capabilities

      public TLspViewBuilder capabilities(ILcdGLCapabilities aGLCapabilities)
      Sets the OpenGL capabilities with which to initialize the view. The capabilities indicate properties such as color depth or the presence of depth/stencil buffers. Capabilities objects can be created using ALcdGLBinding.getInstance().getGLDrawableFactory().createGLCapabilities().
      Parameters:
      aGLCapabilities - the GL capabilities for the view
      Returns:
      this builder
      See Also:

    • shareGLContext

      public TLspViewBuilder shareGLContext(ILcdGLDrawable aGLDrawable)
      Sets an ILcdGLDrawable with which new views should share an OpenGL context. Context sharing allows multiple views to share OpenGL resources such as textures, shaders and buffer objects. By default, this property is null, indicating that no context sharing is performed.

      When the context between two views is shared, the ILspGLResourceCache is automatically shared as well. In that case, the GL resource cache size and max entry count will correspond to the first created view and calls to glResourceCacheSize(long) and glResourceCacheMaxEntries(int) for the other views will be ignored.

      Parameters:
      aGLDrawable - the drawable to share with
      Returns:
      this builder

    • graphicsDevice

      public TLspViewBuilder graphicsDevice(GraphicsDevice aGraphicsDevice)
      Creates a view for a specific, given GraphicsDevice. The default value is null. This method should not be called in most situations; it may (in some rare cases) be necessary in certain multi-screen configurations to create a view on a specific display. This method is only relevant when creating a TLspAWTView or TLspSwingView.
      Parameters:
      aGraphicsDevice - a graphics device
      Returns:
      this builder

    • executorThreadCount

      public TLspViewBuilder executorThreadCount(int aCount)
      Sets the number of threads used by the view's task executor. When this variable is set to 0, the view's task executor will operate completely synchronously, i.e. all tasks will actually be executed on the calling thread. The default thread count is chosen based on the number of CPU cores in the system.
      Parameters:
      aCount - the number of threads used by the view's task executor.
      Returns:
      this builder

    • glResourceCacheSize

      public TLspViewBuilder glResourceCacheSize(long aSize)
      Sets the size (in bytes) used by the OpenGL resource cache.
      The default value is -1, which will trigger an automatic behavior that is suited for most uses. This should only be overridden if you're visualizing exceptionally large or small data.
      The size can also be configured by setting the system property "com.luciad.view.lightspeed.opengl.cacheSize" to a value in megabytes, e.g. "-Dcom.luciad.view.lightspeed.opengl.cacheSize=768".
      Parameters:
      aSize - the size in bytes
      Returns:
      this builder

    • glResourceCacheMaxEntries

      public TLspViewBuilder glResourceCacheMaxEntries(int aCount)
      Sets the maximal number of entries that can be stored in the OpenGL resource cache. The default value is -1, meaning that there is no limit on the count. The maximal entry count can also be configured by setting the system property "com.luciad.view.lightspeed.opengl.maxCacheEntries", e.g. "-Dcom.luciad.view.lightspeed.opengl.maxCacheEntries=2000" to limit the count to 2000 entries.
      Parameters:
      aCount - the maximal entry count. If aCount <= 0 there is no limit on the count.
      Returns:
      this builder

    • paintExceptionHandler

      public TLspViewBuilder paintExceptionHandler(ILcdPaintExceptionHandler aPaintExceptionHandler)
      Sets a paint exception handler for the view. The handler is invoked if an exception should be thrown during the view's paint cycle, also for exceptions thrown by asynchronous tasks. The default handler is a TLcdLoggingPaintExceptionHandler.
      Parameters:
      aPaintExceptionHandler - the new exception handler
      Returns:
      this builder

    • addAtmosphere

      public TLspViewBuilder addAtmosphere(boolean aAddAtmosphere)
      Determines whether an "atmosphere" should be painted in the view. The atmosphere provides a visually pleasing background for 3D views. It has no effect in 2D. This property is on by default.
      Parameters:
      aAddAtmosphere - whether or not to add an atmosphere to new views
      Returns:
      this builder

    • defaultEffects

      public TLspViewBuilder defaultEffects()
      Adds a set of default graphics effects to the view consisting of a sky/atmosphere background, fog, ambient light and a headlight.
      Returns:
      this builder
      Since:
      2013.0
      See Also:

    • viewType

      public TLspViewBuilder viewType(ILspView.ViewType aViewType)
      Determines whether views will be initialized to 2D or 3D. The default is 2D. Views can be switched back and forth between 2D and 3D after creation using TLspViewTransformationUtil.
      Parameters:
      aViewType - the type of view (2D or 3D) to be created
      Returns:
      this builder
      Since:
      2013.0
      See Also:

    • worldReference

      public TLspViewBuilder worldReference(ILcdXYZWorldReference aWorldReference)
      Sets the initial world reference to be assigned to the view. Setting this to null will set a default world reference depending on the view type:
      • A grid reference with an equidistant cylindrical projection for 2D views;
      • A geocentric reference for 3D views.
      In both cases, the default WGS84 geodetic datum is used.
      Parameters:
      aWorldReference - the initial world reference to be assigned to new views
      Returns:
      this builder
      Since:
      2013.0

    • overlayComponents

      public TLspViewBuilder overlayComponents(boolean aOverlayComponents)
      Determines whether other GUI components will need to be overlaid on top of the ILspView after it has been created. Typical examples of overlay components are on-map navigation controls, such as those created by TLspNavigationControlsBuilder. This property is true by default. Switching it off when it is not needed may allow the view to perform some behind-the-scenes optimizations.

      Note that when overlay component support is switched off, ILspAWTView.getOverlayComponent() may return null.

      Note that this method only affects TLspAWTView and TLspExternalView.

      Parameters:
      aOverlayComponents - whether or not overlay components should be supported
      Returns:
      this builder
      Since:
      2013.0

    • disableAutomaticContextSharing

      public TLspViewBuilder disableAutomaticContextSharing()

      A static method to disable automatic context sharing. Automatic context sharing is on for all AWT, Swing and JavaFX views, unless this method is called. If enabled, all created views will share the same OpenGL context and GL resource cache. This function can be overridden by the shareGLContext(com.luciad.view.opengl.binding.ILcdGLDrawable) method, which allows you to group specific views together.

      To elaborate on this mechanism, the following options are possible:

      If disabled, all created views (that do not have an explicit shareGLContext called) will have a distinct OpenGL context and GL resource cache.

      It is strongly recommended to leave automatic context sharing on to be more memory efficient.

      Note: Offscreen views do not support automatic context sharing

      Since:
      2013.0

    • paintingHints

      public TLspViewBuilder paintingHints(TLspViewPaintingHints aPaintingHints)
      Sets the painting hints to be used by created views. The default value is TLspViewPaintingHints.newBuilder().build(). The hints must not be null.
      Parameters:
      aPaintingHints - the painting hints to be used
      Returns:
      this

    • resolutionScale

      public TLspViewBuilder resolutionScale(double aResolutionScale)
      Allows rendering a view at a lower resolution than the view's host component. This has two consequences:
      • the view renders faster and consumes less resources
      • the size of the content in the view (text, lines) is increased
      This is useful for devices with modest resources but high-resolution displays, such as tablets.

      This approach is not compatible with interactive labels, because of the mismatch between the Swing and view component size. Also note that this method has no effect on JavaFX views.

      Parameters:
      aResolutionScale - a value greater than zero and smaller than or equal to 1 (equal resolution)
      Returns:
      this