WaterPolygonEntityVisualizer¶

Extends¶

EntityVisualizer

Constructors¶

new WaterPolygonEntityVisualizer()¶

new WaterPolygonEntityVisualizer(options?): WaterPolygonEntityVisualizer

Parameters¶

Parameter	Type	Description
`options`?	`Option`	生成オプション

Returns¶

WaterPolygonEntityVisualizer

Overrides¶

EntityVisualizer.constructor

Properties¶

REFLECTION_REFINE_MAX¶

static readonly REFLECTION_REFINE_MAX: 10 = 10

画面空間反射の二分探索回数の上限。@see WaterPolygonEntityVisualizer.REFLECTION_STEPS_MAX

REFLECTION_STEPS_MAX¶

static readonly REFLECTION_STEPS_MAX: 64 = WaterFeatures.REFLECTION_STEPS_MAX

画面空間反射のレイマーチのステップ数の上限。

水面シェーダーがこの値で clamp するので、これを超えて渡しても切り捨てられる。上限を 3 箇所 (シェーダー・この setter・UI) に手で書くとずれるため、ここを唯一の出どころにする。

entities¶

protected entities: Entity<EventMap>[]

Inherited from¶

EntityVisualizer.entities

Accessors¶

caustics_scale¶

get caustics_scale(): number

集光の倍率 [0, 2]。設定した値 (品質・水域の種類は掛からない)。

Returns¶

number

current_angle_degree¶

get current_angle_degree(): number

流れていく向き (Degrees、東 0、北 90)。

Returns¶

number

current_speed¶

get current_speed(): number

表層の流れの速さ (m/s)。0 以上。

Returns¶

number

foam_life¶

get foam_life(): number

泡が消えるまでの時定数 (秒、実効値)。読み取りのみ。3.1 s × setFoamLifeScale の倍率。

Returns¶

number

foam_life_scale¶

get foam_life_scale(): number

泡が消えるまでの時間の倍率 [0, 10]。

Returns¶

number

quality¶

get quality(): undefined | Quality

適用済みの描画品質。

WaterPolygonEntityVisualizer.setQuality を呼んでいなければ undefined (状態は Quality.MEDIUM と同じ)。

See¶

WaterPolygonEntityVisualizer.setQuality

Returns¶

undefined | Quality

reflection_refine¶

get reflection_refine(): number

画面空間反射の二分探索の回数 [1, REFLECTION_REFINE_MAX]。

Returns¶

number

reflection_scale¶

get reflection_scale(): number

反射の倍率 [0, 4]。

Returns¶

number

reflection_steps¶

get reflection_steps(): number

画面空間反射のレイマーチのステップ数 [0, REFLECTION_STEPS_MAX]。設定した値 (品質・水域の種類は掛からない)。

Returns¶

number

refraction_scale¶

get refraction_scale(): number

水底の透けの倍率 [0, 1]。設定した値 (品質は掛からない)。

Returns¶

number

seabed¶

get seabed(): Seabed

海底の求め方。

Returns¶

Seabed

seabed_slope¶

get seabed_slope(): number

仮想海底の勾配 (水平距離に対する深さの比)。0 より大きい。

Returns¶

number

shore_break_scale¶

get shore_break_scale(): number

岸で砕ける波の倍率 [0, 1]。設定した値 (品質・水域の種類は掛からない)。

Returns¶

number

specular_scale¶

get specular_scale(): number

照り返しの倍率 [0, 2]。

Returns¶

number

usage¶

get usage(): Usage

水域の種類。

Returns¶

Usage

water_turbidity¶

get water_turbidity(): number

濁り具合 [0, 1]。

Returns¶

number

wave_direction_angle_degree¶

get wave_direction_angle_degree(): number

波が進む向き (Degrees、東 0、北 90、[0, 360))。読み取りのみ。

水に対する風 (風のベクトル − 流れのベクトル) の向き。流れが無ければ wind_angle_degree と同じ。

Returns¶

number

wave_height¶

get wave_height(): number

有義波高を線形和の振幅に写した値 (m)。読み取りのみ。

wave_length と水に対する風速から、発達途上の海の有義波高を求め、 setWaveHeightScale の倍率を掛けた値。風が弱すぎる (0.5 m/s 未満) と 0。

Returns¶

number

wave_height_scale¶

get wave_height_scale(): number

波高の倍率 [0, 4]。

Returns¶

number

wave_length¶

get wave_length(): number

基準波長 (m)。読み取りのみ。

風速 (setWindSpeed)・吹送距離 (setWindFetch)・流れ (setCurrentSpeed) から導く。水に対する風速 U と吹送距離 F から JONSWAP の成長則で波齢 c_p/U を決め、その波齢のピーク波長 2π (c_p/U)² U² / g を取る。波齢の上限は完全発達の約 1.29。直接設定する口は無い。波を長くするには吹送距離を延ばすか風を強める。

Returns¶

number

wave_steepness¶

get wave_steepness(): number

波の急峻度 [0, 0.9]。0 で正弦波。

Returns¶

number

whitecap_scale¶

get whitecap_scale(): number

沖の白波の倍率 [0, 10]。

Returns¶

number

whitecap_strength¶

get whitecap_strength(): number

沖の白波の量 (実効値)。読み取りのみ。導出した量 × setWhitecapScale の倍率。

Returns¶

number

wind_angle_degree¶

get wind_angle_degree(): number

風が吹いていく向き (Degrees、東 0、北 90)。

Returns¶

number

wind_fetch¶

get wind_fetch(): number

吹送距離 (m)。1 以上。

Returns¶

number

wind_speed¶

get wind_speed(): number

海面から 10m の風速 (m/s)。0 以上。

Returns¶

number

Methods¶

applyPreset()¶

applyPreset(preset)¶

applyPreset(preset): void

水域プリセットを適用する。

風・波・水の色・泡の組み合わせを、対応する既存の public setter 経由でまとめて適用する (各 setter の clamp や非有限値の無視も通常どおり発生する)。

描画品質 (setQuality) と水域の種類 (Usage) は別の軸で、設定した値を書き換えずに描くかどうかだけを決める。呼ぶ順序はどちらが先でもよい。

水面高 (setWaterPolygonEntityHeight) と海底の求め方 (setSeabed) は場所が決めるものなので、ライブラリ組み込みのプリセットは変更しない。

Parameters¶

Parameter	Type	Description
`preset`	`Preset`	水域プリセット

Returns¶

void

Throws¶

Error 未知のプリセットを指定した場合

applyPreset(values)¶

applyPreset(values): void

任意の設定値をまとめて適用する。

指定されたフィールドだけが、対応する setter と同じ検証を通して適用される。省略されたフィールドは現在値のまま変わらない。

Parameters¶

Parameter	Type	Description
`values`	`PresetValues`	適用する設定値

Returns¶

void

applyPreset(preset)¶

applyPreset(preset): void

Parameters¶

Parameter	Type
`preset`	`Preset` \| `PresetValues`

Returns¶

void

See¶

applyPreset

destroy()¶

destroy(): void

Returns¶

void

Overrides¶

EntityVisualizer.destroy

dispose()¶

dispose(): void

Returns¶

void

Overrides¶

EntityVisualizer.dispose

getEntitiesCount()¶

getEntitiesCount(): number

Returns¶

number

Inherited from¶

EntityVisualizer.getEntitiesCount

getEntity()¶

getEntity(idx): null | Entity<EventMap>

Parameters¶

Parameter	Type
`idx`	`number`

Returns¶

null | Entity<EventMap>

Inherited from¶

EntityVisualizer.getEntity

getMaterial()¶

getMaterial(viewer): Material

Parameters¶

Parameter	Type
`viewer`	`Viewer`

Returns¶

Material

Overrides¶

EntityVisualizer.getMaterial

getSeabedRockColor()¶

getSeabedRockColor(dst): Vector3

水底の礫の反射率。

Parameters¶

Parameter	Type	Description
`dst`	`Vector3`	書き込み先

Returns¶

Vector3

dst。線形の反射率 [ r, g, b ]、各成分 [0, 1]

See¶

setSeabedRockColor

getSeabedSandColor()¶

getSeabedSandColor(dst): Vector3

水底の砂の反射率。

Parameters¶

Parameter	Type	Description
`dst`	`Vector3`	書き込み先

Returns¶

Vector3

dst。線形の反射率 [ r, g, b ]、各成分 [0, 1]

See¶

setSeabedSandColor

getWaterPolygonEntities()¶

getWaterPolygonEntities(): IterableIterator<WaterPolygonEntity, any, any>

Returns¶

IterableIterator<WaterPolygonEntity, any, any>

setCausticsScale()¶

setCausticsScale(value): void

集光 (コースティクス) の倍率。水底に届く直達光の明暗に掛ける。

波の峰がレンズになって水底に光を集める。画素ごとに水面の曲率 (高さの 2 階微分 ∇²h) と水深 d から集光の利得 G = max(1 + c·d·∇²h, 0) を求め、水底の直達光を E_直達 × (1 + 倍率 × (G − 1)) にする。倍率 1 が物理的に正しい倍率、0 で集光なし。利得の空間平均は 1 なので、倍率を変えても水底の平均の明るさは変わらない。

水底が透けて見えないと効かないので、setRefractionScale が 0 の間は描かない。描画品質 Quality.HIGH 以外と水域の種類 Usage.OFFSHORE でも描かない (設定した値は残る)。

Parameters¶

Parameter	Type	Description
`value`	`number`	倍率 [0, 2]。範囲外は切り詰め、非有限値は無視する

Returns¶

void

Default Value¶

0.4

setCurrentAngleDegree()¶

setCurrentAngleDegree(value): void

流れていく向きを設定する。

風の向き (setWindAngleDegree) と同じ基準。

Parameters¶

Parameter	Type	Description
`value`	`number`	向き (Degrees)。地図の東を 0、北を 90 とする反時計回り (MLOCS)。非有限値は無視する

Returns¶

void

Default Value¶

0

setCurrentSpeed()¶

setCurrentSpeed(value): void

表層の流れの速さを設定する。0 で流れなし。

流れは 2 つの形で効く。 1. 波の模様は水に乗って運ばれるので、地面から見た波の速さは「水に対する位相速度 + 流速の波向き成分」になる (流れの中の深水波の分散関係 (ω − k·U_c)² = g k)。 2. 波を育てるのは水に対する風 (風 − 流れ) なので、風と向かい合う流れでは波が高く白波が多く、風と同じ向きの流れでは波が低くなる。無風でも流れがあれば、水に対する風が生じて波が立つ。

流れは水面全体で一様とみなす。流れの速さが場所で変わる所 (潮目・河口) の波の変形は扱わない。

Parameters¶

Parameter	Type	Description
`value`	`number`	速さ (m/s)。0 以上。負は 0 に切り詰め、非有限値は無視する

Returns¶

void

Default Value¶

0

setEntityAltitudeMode()¶

setEntityAltitudeMode(altitude_mode): void

高度モードの一括設定は受け付けない。

水面は絶対高さのみ (WaterPolygonEntity.altitude_mode)。基底の実装はエンティティへ順に代入するので、弾かずに任せると途中まで設定されてから例外が飛ぶ。

Parameters¶

Parameter	Type
`altitude_mode`	`AltitudeMode`

Returns¶

void

Overrides¶

EntityVisualizer.setEntityAltitudeMode

Deprecated¶

水面は高度モードを持たない。呼ぶ必要は無い。

setFoamLifeScale()¶

setFoamLifeScale(value): void

砕けた泡が消えるまでの時間の倍率。

泡の面積は時定数 τ で exp(−t/τ) のように減る。τ = 3.1 s × 倍率。3.1 s は外洋の観測で白波の泡が消える時間 1.4〜4.8 s (Callaghan, Deane, Stokes 2012) の中央。 0 で泡の履歴を持たず、その場の砕波条件だけで泡を出す。0 より大きいと泡を移流・減衰させる追加パスが 1 本走り、砕けた跡が水面に残る。描画品質 Quality.MINIMAL / Quality.LOW では履歴を持たない (設定した値は残る)。

Parameters¶

Parameter	Type	Description
`value`	`number`	倍率 [0, 10]。範囲外は切り詰め、非有限値は無視する

Returns¶

void

Default Value¶

6.0 / 3.1 (時定数 6 秒)

setPrimitiveProperties()¶

setPrimitiveProperties(viewer, props, entity?): boolean

Parameters¶

Parameter Type Description

viewer Viewer -

props object -

entity?

WaterPolygonEntity

プロパティを設定する対象のエンティティ。

エンティティごとに違う値を渡す必要がある実装 (水面の汀線マップ等)

が使う。使わない実装は無視してよい。

Returns¶

boolean

Overrides¶

EntityVisualizer.setPrimitiveProperties

setQuality()¶

setQuality(value): void

描画品質プリセットを適用する。

水域プリセット (WaterPolygonEntityVisualizer.applyPreset) とは軸が違い、負荷の大きい経路 (画面空間反射・屈折・コースティクス・泡の履歴・汀線波・書き込み先のテクスチャの解像度・波の評価コスト) を段階的に止める。止めるだけで、設定された値 (setter とプリセットが書いたもの) は書き換えない。そのため水域プリセットとの順序に依らず同じ結果になり、品質を上げ直すと設定した値のとおりに戻る。getter が返すのも設定した値。

止めた追加パスは書き込み先 (FBO とテクスチャ) を手放す。シェーダーは残すので、上げ直してもコンパイルし直さない。

Parameters¶

Parameter	Type	Description
`value`	`Quality`	描画品質

Returns¶

void

Throws¶

Error 未知の品質を指定した場合

Default Value¶

当てるまでは {@link Quality.MEDIUM} と同じ状態

setReflectionRefine()¶

setReflectionRefine(value): void

画面空間反射の二分探索の回数。

ステップ数と違い setQuality は触らない。歩幅が粗い品質ほど必要な回数は増えるので、品質で下げると残差の要件を満たせなくなる。

Parameters¶

Parameter	Type	Description
`value`	`number`	回数 [1, REFLECTION_REFINE_MAX]。整数に丸めて切り詰め、非有限値は無視する

Returns¶

void

Default Value¶

8

setReflectionScale()¶

setReflectionScale(value): void

反射の倍率。水面が空や周りを映す割合 (フレネル反射率 F) に掛ける。

水面の色は mix(水中から戻る光, 映り込み, F) で、F は Schlick の近似 F = F0 + (1 − F0)(1 − cosθ)⁵ (F0 = 0.02、θ は視線と波の法線のなす角)。倍率は F に掛け、 1 を超えた分は切る。合成比が変わるだけなので、水面全体が明るくなることは無い。太陽と月の照り返しは別 (setSpecularScale)。

Parameters¶

Parameter	Type	Description
`value`	`number`	倍率 [0, 4]。範囲外は切り詰め、非有限値は無視する

Returns¶

void

Default Value¶

1

setReflectionSteps()¶

setReflectionSteps(value): void

画面空間反射のレイマーチのステップ数。0 で探索しない。

描画品質はこれを頭打ちにする (Quality.LOW と Quality.MEDIUM は 20 ステップ、 Quality.MINIMAL と水域の種類 Usage.OFFSHORE は探索しない)。設定した値は書き換えないので、品質を上げ直すとこのステップ数に戻る。

Parameters¶

Parameter	Type	Description
`value`	`number`	ステップ数 [0, REFLECTION_STEPS_MAX]。整数に丸めて切り詰め、非有限値は無視する

Returns¶

void

Default Value¶

40

setRefractionScale()¶

setRefractionScale(value): void

水底の透けの倍率。水中から戻る光のうち、水底で反射して戻る分に掛ける。

水底がどれだけ見えるかは物理で決まる。水柱の往復の透過率 exp(−(σa + b_b) L_光 − σt L_視線) (σ は setWaterTurbidity が決める吸収・散乱係数、L は屈折した光路長) と、水面のフレネル透過率である。この倍率はその結果に掛ける。0 で水底を描かず、水柱の散乱光だけの不透明な水面になる (水柱を深水まで飽和させる)。

描画品質 Quality.MINIMAL / Quality.LOW では描かない (設定した値は残る)。半透明の地表を HDR で描くフレームでは、透かす水底のコピーが無いので反映されない。

Parameters¶

Parameter	Type	Description
`value`	`number`	倍率 [0, 1]。範囲外は切り詰め、非有限値は無視する

Returns¶

void

Default Value¶

0.76

setSeabed()¶

setSeabed(value): void

海底の求め方。既定 Seabed.VIRTUAL。

打ち寄せ波の波長と砕波の判定は水深で決まる。その水深をどこから取るかを選ぶ。汀線マップに書き込むので、変えると作り直しが走る。

Seabed.REAL DEM を海底として使う。内陸の湖・ダム・河川向け。
Seabed.VIRTUAL 岸からの距離に一定勾配を掛ける。外洋向け。
Seabed.MIXED 標高が海面付近のセルだけ仮想にし、残りは DEM。

自動判定にしないのは、海の DEM が海底を 0m にクランプしているため。実 DEM を素直に信じると水深が水面高ぶんにしかならず仮想より悪くなる。海か内陸かはアプリが知っている。

Parameters¶

Parameter	Type
`value`	`Seabed`

Returns¶

void

setSeabedRockColor()¶

setSeabedRockColor(color): void

水底の礫の反射率。

Parameters¶

Parameter Type Description

color

Vector3

線形 (sRGB ではない) の反射率 [ r, g, b ]。各成分 [0, 1]。

範囲外は切り詰め、非有限値の成分は無視する

Returns¶

void

Throws¶

Error 要素が 3 つに満たない場合

See¶

setSeabedSandColor

setSeabedSandColor()¶

setSeabedSandColor(color): void

水底の砂の反射率。

手続き的な水底を、この砂と礫の 2 色でノイズと水深から混ぜる。照度は含まない。

Parameters¶

Parameter Type Description

color

Vector3

線形 (sRGB ではない) の反射率 [ r, g, b ]。各成分 [0, 1]。

範囲外は切り詰め、非有限値の成分は無視する

Returns¶

void

Throws¶

Error 要素が 3 つに満たない場合

setSeabedSlope()¶

setSeabedSlope(value): void

仮想海底の勾配を設定する。

Seabed.VIRTUAL と、Seabed.MIXED が仮想へ回したセルで、岸からの距離にこの値を掛けて水深とする。砂浜で 2% 前後。汀線マップに書き込むので、変えると作り直しが走る。

Parameters¶

Parameter	Type	Description
`value`	`number`	勾配 (水平距離に対する深さの比)。0 より大きい値。それ以外と非有限値は無視する

Returns¶

void

Default Value¶

0.02

setShoreBreakScale()¶

setShoreBreakScale(value): void

岸で砕ける波の倍率。岸に打ち寄せる波の振れ幅と、砕けて汀線に溜まる泡の量に掛ける。

打ち寄せる波は、汀線マップの岸までの距離と向きから、峰が汀線に平行で岸へ向かう波を作る。泡は、水深 h に対して波の振れ幅 H が H/h > 1.79 となる峰で生まれる。1.79 は孤立波の砕波条件 H > 0.78h (McCowan 1894) を、汀線マップの水深と振れ幅の尺度に合わせて目視で決めた比。どちらも物理的な判定で場所が決まり、この倍率は強さだけを変える。水深で砕ける波なので風の白波 (setWhitecapScale) とは独立で、風が弱く白波が無くても出る。

汀線は水面ポリゴンの境界リングと、DEM から削り出した陸のきわの両方から取る。描画品質 Quality.MINIMAL / Quality.LOW と水域の種類 Usage.OFFSHORE では描かない (設定した値は残り、品質を上げると反映される)。

Parameters¶

Parameter	Type	Description
`value`	`number`	倍率 [0, 1]。0 で打ち寄せる波も泡も無し。範囲外は切り詰め、非有限値は無視する

Returns¶

void

Default Value¶

0.3

setSpecularScale()¶

setSpecularScale(value): void

太陽と月の照り返し (鏡面のギラつき) の倍率。1 が物理的に正しい倍率。

照り返しは GGX の鏡面反射に太陽・月の照度を掛けたもの。物理的に正しい値では輝度が表示域を数桁超え、水面が白い面になってブルームで水際の地表まで滲むので、既定は 0.1 に抑えている。

Parameters¶

Parameter	Type	Description
`value`	`number`	倍率 [0, 2]。範囲外は切り詰め、非有限値は無視する

Returns¶

void

Default Value¶

0.1

setWaterPolygonEntityHeight()¶

setWaterPolygonEntityHeight(height): void

Parameters¶

Parameter	Type
`height`	`number`

Returns¶

void

setWaterTurbidity()¶

setWaterTurbidity(value): void

濁り具合。0 が純水、1 が濁った湖。

吸光係数・散乱率・色が飽和する水深をまとめて決める。濁りは主に黄色物質 (CDOM) と懸濁粒子で、前者は青を強く吸い、後者は散乱を増やして波長依存を弱める。そのため濁るほど青が抜けて緑〜褐色に寄り、見通しが悪くなる。

Parameters¶

Parameter	Type	Description
`value`	`number`	濁り [0, 1]。範囲外は切り詰め、非有限値は無視する

Returns¶

void

setWaveHeightScale()¶

setWaveHeightScale(value): void

波高の倍率。風から導いた波高に掛ける。

波高そのものは物理で決まる (wave_height)。地図の縮尺で波を強調したいときや、穏やかに見せたいときに使う。波長・位相速度・白波の量は変わらない。

Parameters¶

Parameter	Type	Description
`value`	`number`	倍率 [0, 4]。範囲外は切り詰め、非有限値は無視する

Returns¶

void

Default Value¶

1

setWaveSteepness()¶

setWaveSteepness(value): void

波の急峻度。

0 で正弦波、上げると峰が進行方向へ尖る。水平変位を伴うので波が「運ばれる」ように見える。1 に近づくと峰が自己交差する。

Parameters¶

Parameter	Type	Description
`value`	`number`	急峻度 [0, 0.9]。範囲外は切り詰め、非有限値は無視する

Returns¶

void

setWhitecapScale()¶

setWhitecapScale(value): void

沖の白波の倍率。風から導いた白波の量に掛ける。岸で砕ける波の泡 (setShoreBreakScale) には効かない。

白波の量は、水に対する風速から海面の白波被覆率 (Monahan & O'Muircheartaigh 1980) を求め、既定の水面に合わせて較正し 1 で頭打ちにしたもの。この倍率はその結果に掛ける (whitecap_strength)。描画品質 Quality.MINIMAL では描かない (設定した値は残る)。

Parameters¶

Parameter	Type	Description
`value`	`number`	倍率 [0, 10]。0 で白波なし。範囲外は切り詰め、非有限値は無視する

Returns¶

void

Default Value¶

1

setWindAngleDegree()¶

setWindAngleDegree(value): void

風が吹いていく向き (= 風で立つ波が進む向き) を設定する。

気象でいう風向 (風が吹いてくる向き) とは 180 度逆なので注意する。北風 (北から吹く風) は南へ吹いていくので 270。流れがあるときは、波の向きは水に対する風 (風 − 流れ) の向きになる (wave_direction_angle_degree)。

Parameters¶

Parameter Type Description

value

number

向き (Degrees)。地図の東を 0、北を 90 とする反時計回り (MLOCS)。

非有限値は無視する

Returns¶

void

Default Value¶

195.65

setWindFetch()¶

setWindFetch(value): void

吹送距離を設定する。風上の岸からこの水面までの距離で、波がどこまで育つかを決める。

同じ風でも海と湖と川で波がまるで違うのは、この距離が違うため。距離が短いほど波は若く、短く、急峻になる。十分に長いと完全発達 (波齢約 1.29) で頭打ちになる。目安は、川 100 m 前後、小さな湖 500 m〜2 km、湾 10〜30 km、外洋 30 km 以上 (完全発達の波は地図の縮尺では長すぎるので、地図で見せる外洋は完全発達より手前の距離を使う)。

Parameters¶

Parameter	Type	Description
`value`	`number`	吹送距離 (m)。1 未満は 1 に切り上げ、非有限値は無視する

Returns¶

void

Default Value¶

2000

setWindSpeed()¶

setWindSpeed(value): void

風速を設定する。波長・波高・位相速度・白波の量はこれと吹送距離と流れから決まる。

波を育てるのは水に対する風 (風のベクトル − 流れのベクトル) で、その大きさ U で波が育つ (wave_length、wave_height、whitecap_strength)。 0.5 m/s 未満では波高と白波が 0 になる (波長は 0.5 m/s の値を保つ)。

Parameters¶

Parameter Type Description

value

number

海面から 10m の高さの風速 (m/s)。気象の予報値や観測値をそのまま渡せる。

0 以上。負は 0 に切り詰め、非有限値は無視する

Returns¶

void

Default Value¶

16.9 (既定の水面、波長約 6 m・波高約 0.65 m に当たる風)