Package com.luciad.maps.effects

Class EnvironmentMap.CubeMapBuilder

java.lang.Object

com.luciad.maps.effects.EnvironmentMap.CubeMapBuilder

All Implemented Interfaces:

AutoCloseable

Enclosing class:

EnvironmentMap

public static final class EnvironmentMap.CubeMapBuilder
extends Object
implements AutoCloseable

Builder for an EnvironmentMap from six cubemap faces.

All six faces are mandatory and must be square and equally sized. The faces are uploaded directly into a GPU cube texture, which requires square faces of matching dimensions. Non-square or differently sized faces are not supported.

The faces make up the six sides of a cube centered on the camera. Each face image is oriented as you would see it looking outward at that side, with orientation 0 (north) pointing along the front face. Unfolded, the faces lay out as the following cross:

 +--------+
              |  top   |
     +--------+--------+--------+--------+
     |  left  | front  | right  |  back  |
     +--------+--------+--------+--------+
              | bottom |
              +--------+
 

At orientation 0, the faces map to world directions as: front = north, right = east, back = south, left = west, top = up, bottom = down.

Since:

2026.1

Constructor Summary

Constructors

Constructor	Description
CubeMapBuilder(EnvironmentMap.CubeMapBuilder other)	Copy constructor.

Method Summary

Modifier and Type	Method	Description
EnvironmentMap.CubeMapBuilder	back(Image back)	Sets the back face.
EnvironmentMap.CubeMapBuilder	bottom(Image bottom)	Sets the bottom face.
EnvironmentMap	build()	Builds the environment map.
void	close()
protected void	finalize()
EnvironmentMap.CubeMapBuilder	front(Image front)	Sets the front face.
EnvironmentMap.CubeMapBuilder	intensity(double intensity)	Sets the brightness of the environment, as a non-negative factor by which the environment color is multiplied.
EnvironmentMap.CubeMapBuilder	left(Image left)	Sets the left face.
EnvironmentMap.CubeMapBuilder	orientation(Azimuth orientation)	Sets the heading of the environment.
EnvironmentMap.CubeMapBuilder	right(Image right)	Sets the right face.
EnvironmentMap.CubeMapBuilder	top(Image top)	Sets the top face.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

CubeMapBuilder

public CubeMapBuilder(@NotNull
 EnvironmentMap.CubeMapBuilder other)

Copy constructor.

Parameters:

other - the builder to copy.

Method Details

finalize

protected void finalize()

Overrides:

finalize in class Object

close

public void close()

Specified by:

close in interface AutoCloseable

front

@NotNull
public EnvironmentMap.CubeMapBuilder front(@NotNull
 Image front)
                                    throws NullPointerException,
IllegalArgumentException

Sets the front face.

This is mandatory. The image must be square.

Parameters:

front - the front face. Cannot be null.

Returns:

this builder.

Throws:

NullPointerException - when the image is null.

IllegalArgumentException - when the image is not square.

back

@NotNull
public EnvironmentMap.CubeMapBuilder back(@NotNull
 Image back)
                                   throws NullPointerException,
IllegalArgumentException

Sets the back face.

This is mandatory. The image must be square.

Parameters:

back - the back face. Cannot be null.

Returns:

this builder.

Throws:

NullPointerException - when the image is null.

IllegalArgumentException - when the image is not square.

left

@NotNull
public EnvironmentMap.CubeMapBuilder left(@NotNull
 Image left)
                                   throws NullPointerException,
IllegalArgumentException

Sets the left face.

This is mandatory. The image must be square.

Parameters:

left - the left face. Cannot be null.

Returns:

this builder.

Throws:

NullPointerException - when the image is null.

IllegalArgumentException - when the image is not square.

right

@NotNull
public EnvironmentMap.CubeMapBuilder right(@NotNull
 Image right)
                                    throws NullPointerException,
IllegalArgumentException

Sets the right face.

This is mandatory. The image must be square.

Parameters:

right - the right face. Cannot be null.

Returns:

this builder.

Throws:

NullPointerException - when the image is null.

IllegalArgumentException - when the image is not square.

bottom

@NotNull
public EnvironmentMap.CubeMapBuilder bottom(@NotNull
 Image bottom)
                                     throws NullPointerException,
IllegalArgumentException

Sets the bottom face.

This is mandatory. The image must be square.

Parameters:

bottom - the bottom face. Cannot be null.

Returns:

this builder.

Throws:

NullPointerException - when the image is null.

IllegalArgumentException - when the image is not square.

top

@NotNull
public EnvironmentMap.CubeMapBuilder top(@NotNull
 Image top)
                                  throws NullPointerException,
IllegalArgumentException

Sets the top face.

This is mandatory. The image must be square.

Parameters:

top - the top face. Cannot be null.

Returns:

this builder.

Throws:

NullPointerException - when the image is null.

IllegalArgumentException - when the image is not square.

orientation

@NotNull
public EnvironmentMap.CubeMapBuilder orientation(@NotNull
 Azimuth orientation)

Sets the heading of the environment.

The default is north (0 degrees).

Parameters:

orientation - the heading of the environment.

Returns:

this builder.

intensity

@NotNull
public EnvironmentMap.CubeMapBuilder intensity(double intensity)
                                        throws IllegalArgumentException

Sets the brightness of the environment, as a non-negative factor by which the environment color is multiplied.

This method is optional. If it is not called, the intensity is 1, which paints the imagery as-is. Values above 1 brighten the environment and values below 1 darken it: 2 is twice as bright and 0.5 is half as bright. A value of 0 paints an environment black and leaves a reflection map casting no light.

Parameters:

intensity - the brightness factor applied to the environment. Must not be negative.

Returns:

this builder.

Throws:

IllegalArgumentException - when the intensity is negative.

build

@NotNull
public EnvironmentMap build()
                     throws IllegalStateException

Builds the environment map.

Returns:

the built environment map.

Throws:

IllegalStateException - when any of the six faces was not set.

IllegalStateException - when the faces do not all have the same dimensions.