ALspStyle is the abstract base class from which all styles are extended. As a user of the API, you do not have to create your own extensions. It is recommended to use the concrete styles that are available in the API instead. These are discussed in Visualizing vector data and Visualizing raster data.

Properties shared by style implementations

All styles that extend from ALspStyle have a number of properties in common:

Immutable

The properties of a given style can never change, but the API does allow you to easily derive a new style based on an existing one, as described in Deriving a new style from an existing one.

Simple properties

Styles only contain simple properties that can be queried. This makes it easier to write user interfaces that show the properties of a given style, and allows persisting styles.

Combinable

All styles are kept as simple as possible, but you can combine individual styles with each other to achieve a certain effect. This is why there is no halo property in a basic line style. You can achieve a halo effect by combining two line styles, however.

Setting visual style properties

Two styling properties are available at the level of ALspStyle, and are shared by all styles:

  • isTransparent(): determines whether objects are transparent or opaque. Transparent objects receive special treatment from the view to ensure that their colors are correctly blended with other objects. It is important that this flag is set correctly: if an object is marked as opaque but a non-opaque fill color is specified, the object and other objects which overlap with it on the screen may be rendered incorrectly. Conversely, flagging an object as transparent but using an opaque fill color adversely affects performance.

  • getZOrder(): Determines which place a style takes in an overlapping range of styles. If you define multiple styles of the same type for a given object, you can also define the Z-order of each style. This property reflects that. Styles are applied from lowest to highest Z-order.

Assigning a different Z-order to each object may significantly affect performance. Therefore, try to keep the assignment of Z-orders to individual objects to a minimum.

Creating styles with builders

All styles expose a Builder that allows you to create new styles from scratch, or copy the properties of an existing style.

Using a builder to create new styles

Program: Using a builder to create a line style illustrates the creation of a TLspLineStyle.

Program: Using a builder to create a line style
TLspLineStyle s = TLspLineStyle.newBuilder()
    .color( Color.black )
    .width( 3f )
    .elevationMode( ON_TERRAIN )
    .build();

This code fragment creates a line style which is three pixels wide, solid black and draped on the terrain in 3D.

Deriving a new style from an existing one

Styles are immutable. If you want to modify a style, you cannot simply change one of its properties. Instead, the LuciadLightspeed API provides a convenient way to create a new style from an existing style: base your style builder on the existing style, and add the required property modification. This is shown in Program: Deriving a new style.

Program: Deriving a new style
TLspLineStyle existingStyle = ...;
TLspLineStyle s = existingStyle.asBuilder()
    .width( 4f )
    .build();