Struct veloren_common::terrain::map::MapConfig

pub struct MapConfig<'a> {

    pub map_size_lg: MapSizeLg,
    pub dimensions: Vec2<usize>,
    pub focus: Vec3<f64>,
    pub gain: f32,
    pub fov: f64,
    pub scale: f64,
    pub light_direction: Vec3<f64>,
    pub horizons: Option<&'a [(Vec<f32>, Vec<f32>); 2]>,
    pub is_basement: bool,
    pub is_water: bool,
    pub is_ice: bool,
    pub is_shaded: bool,
    pub is_temperature: bool,
    pub is_humidity: bool,
    pub is_debug: bool,
    pub is_contours: bool,
    pub is_height_map: bool,
    pub is_stylized_topo: bool,
}

Fields

map_size_lg: MapSizeLg

Base two logarithm of the chunk dimensions of the base map. Has no default; set explicitly during initial orthographic projection.

dimensions: Vec2<usize>

Dimensions of the window being written to.

Defaults to 1 << [MapConfig::map_size_lg].

focus: Vec3<f64>

x, y, and z of top left of map.

Default x and y are 0.0; no reasonable default for z, so set during initial orthographic projection.

gain: f32

Altitude is divided by gain and clamped to [0, 1]; thus, decreasing gain makes smaller differences in altitude appear larger.

No reasonable default for z; set during initial orthographic projection.

fov: f64

fov is used for shading purposes and refers to how much impact a change in the z direction has on the perceived slope relative to the same change in x and y.

It is stored as cos θ in the range (0, 1] where θ is the FOV “half-angle” used for perspective projection. At 1.0, we treat it as the limit value for θ = 90 degrees, and use an orthographic projection.

Defaults to 1.0.

FIXME: This is a hack that tries to incorrectly implement a variant of perspective projection (which generates ∂P/∂x and ∂P/∂y for screen coordinate P by using the hyperbolic function [assuming frustum of [l, r, b, t, n, f], rh coordinates, and output from -1 to 1 in s/t, 0 to 1 in r, and NDC is left-handed [so visible z ranges from -n to -f]]):

P.s(x, y, z) = -1 + 2(-n/z x - l) / ( r - l) P.t(x, y, z) = -1 + 2(-n/z y - b) / ( t - b) P.r(x, y, z) = 0 + -f(-n/z - 1) / ( f - n)

Then arbitrarily using W_e_x = (r - l) as the width of the projected image, we have W_e_x = 2 n_e tan θ ⇒ tan Θ = (r - l) / (2n_e), for a perspective projection

(where θ is the half-angle of the FOV).

Taking the limit as θ → 90, we show that this degenerates to an orthogonal projection:

lim{n → ∞}(-f(-n / z - 1) / (f - n)) = -(z - -n) / (f - n).

(Proof not currently included, but has been formalized for the P.r case in Coq-tactic notation; the proof can be added on request, but is large and probably not well-suited to Rust documentation).

For this reason, we feel free to store fov as cos θ in the range (0, 1].

However, fov does not actually work properly yet, so for now we just treat it as a visual gimmick.

scale: f64

Scale is like gain, but for x and y rather than z.

Defaults to (1 << world_size_lg).x / dimensions.x (NOTE: fractional, not integer, division!).

light_direction: Vec3<f64>

Vector that indicates which direction light is coming from, if shading is turned on.

Right-handed coordinate system: light is going left, down, and “backwards” (i.e. on the map, where we translate the y coordinate on the world map to z in the coordinate system, the light comes from -y on the map and points towards +y on the map). In a right handed coordinate system, the “camera” points towards -z, so positive z is backwards “into” the camera.

“In world space the x-axis will be pointing east, the y-axis up and the z-axis will be pointing south”

Defaults to (-0.8, -1.0, 0.3).

horizons: Option<&'a [(Vec<f32>, Vec<f32>); 2]>

If Some, uses the provided horizon map.

Defaults to None.

is_basement: bool

If true, only the basement (bedrock) is used for altitude; otherwise, the surface is used.

Defaults to false.

is_water: bool

If true, water is rendered; otherwise, the surface without water is rendered, even if it is underwater.

Defaults to true.

is_ice: bool

When is_water is true, controls whether an ice layer should appear on that water.

Defaults to true.

is_shaded: bool

If true, 3D lighting and shading are turned on. Otherwise, a plain altitude map is used.

Defaults to true.

is_temperature: bool

If true, the red component of the image is also used for temperature (redder is hotter). Defaults to false.

is_humidity: bool

If true, the blue component of the image is also used for humidity (bluer is wetter).

Defaults to false.

is_debug: bool

Record debug information.

Defaults to false.

is_contours: bool

If true, contour lines are drawn on top of the base rbg

Defaults to false.

is_height_map: bool

If true, a yellow/terracotta heightmap shading is applied to the terrain and water is a faded blue.

Defaults to false

is_stylized_topo: bool

Applies contour lines as well as color modifications

Defaults to false

Implementations

impl<'a> MapConfig<'a>

pub fn orthographic( map_size_lg: MapSizeLg, z_bounds: RangeInclusive<f32> ) -> Self

Constructs the configuration settings for an orthographic projection of a map from the top down, rendering (by default) the complete map to an image such that the chunk:pixel ratio is 1:1.

Takes two arguments: the base two logarithm of the horizontal map extent (in chunks), and the z bounds of the projection.

pub fn map_size_lg(&self) -> MapSizeLg

Get the base 2 logarithm of the underlying map size.

pub fn generate( &self, sample_pos: impl Fn(Vec2<i32>) -> MapSample, sample_wpos: impl Fn(Vec2<i32>) -> f32, write_pixel: impl FnMut(Vec2<usize>, (u8, u8, u8, u8)) ) -> MapDebug

Generates a map image using the specified settings. Note that it will write from left to write from (0, 0) to dimensions - 1, inclusive, with 4 1-byte color components provided as (r, g, b, a). It is up to the caller to provide a function that translates this information into the correct format for a buffer and writes to it.

sample_pos is a function that, given a chunk position, returns enough information about the chunk to attempt to render it on the map. When in doubt, try using MapConfig::sample_pos for this.

sample_wpos is a simple function that, given a column position, returns the approximate altitude at that column. When in doubt, try using MapConfig::sample_wpos for this.