Render Effects¶

トーンマップ ACES

RenderEffects は、描き終えたシーンを画面へ出すときの処理を設定します。トーンマップ、ブルーム (明るい部分のにじみ)、自動露出、光芒 (サンシャフト)、出力ガンマを扱います。Viewer が 1 つ持っていて、viewer.render_effects から触ります。

// Viewer の生成時に置く
const viewer = new mapray.Viewer( "mapray-container", {
    // ...
    atmosphere: new mapray.Atmosphere(),
    render_effects: {
        tonemap_mode: mapray.TonemapMode.ACES,
        bloom_intensity: 0.02,
        sun_shafts_enabled: true,
    },
} );

// 後から変える
viewer.render_effects.setBloomIntensity( 0.05 );

Viewer.Option.render_effects で省略した項目は既定値になります。各項目の範囲と既定値はリファレンスマニュアルを参照してください。生成時の値も setter を通すので、範囲の切り詰めは同じように掛かります。数値の setter は、有限でない値 (NaN、Infinity) を無視します。

HDR パイプライン¶

トーンマップ・ブルーム・自動露出・光芒は、シーンを HDR (物理的な輝度) のまま描いてから画面へ圧縮する「HDR パイプライン」の上で動きます。パイプラインを使うかどうかは setHDRMode() で選びます。

モード	動作
`"auto"`	大気があり、大気が有効で、大気の描画品質が `minimal` 以外のときだけ使います。大気が無ければ使いません
`"on"`	常に使います。大気を持たない `Viewer` でもトーンマップ・ブルーム・自動露出・光芒が使えます
`"off"`	使いません。キャンバスへ直接描きます

HDR パイプラインを使わないフレームでは:

空・太陽・月・雲・水面は、シェーダーの中で同じトーンマップ (tonemap_mode、apply_gamma) と露出 (tonemap_exposure × 大気の露出) を掛けます。明るさの基準は変わりません
ブルーム・自動露出・光芒は効きません
地形・建物・点群は大気ライティングを掛けず、時刻に依らない固定のライティングで描きます

`"auto"`	`"off"`

浮動小数点のカラーバッファに描けない環境では、どのモードでもパイプラインを使いません。大気を持つ Viewer か、モードが "on" のときは、コンソールに警告を 1 回出します。このとき大気も無効になります
大気を持たない Viewer で "on" にしたときは、ブルームと光芒を使い、アンチエイリアスはマルチサンプルになります (大気の品質 medium と同じ扱い)。Viewer.Option.background_color は効かず、空の部分は黒になります

大気の品質との関係¶

HDR パイプラインの中身は、大気の描画品質 (viewer.atmosphere.setQuality()) で変わります。

設定	`minimal`	`low`	`medium`	`high`
HDR パイプライン (`"auto"`)	使わない	使う	使う	使う
トーンマップ・露出・ガンマ	シェーダー内で効く	効く	効く	効く
ブルーム	効かない	効かない	効く	効く
光芒	効かない	効かない	効く	効く
自動露出	効かない	効く	効く	効く
アンチエイリアス	ブラウザ標準	なし	マルチサンプル	マルチサンプル (サンプル数が多い)

minimal と HDR モード "off" はキャンバスへ直接描くので、ブラウザが持つキャンバスのアンチエイリアスが効きます (サンプル数はブラウザが決めます)。low にはアンチエイリアスがありません
minimal で HDR モードを "on" にした場合は、パイプラインを使いますがブルームと光芒は効きません (low と同じ)
マルチサンプルのサンプル数は実行環境の上限を超えません。浮動小数点カラーのマルチサンプルに対応しない環境では、後処理のアンチエイリアス (FXAA) に切り替わります

全体の表は描画品質を参照してください。

トーンマップ¶

setTonemapMode — トーンマップの種類¶

HDR の輝度を画面の輝度域へ圧縮する曲線を選びます。

ACES `"aces"`	Exponential `"exponential"`	PBR Neutral `"pbr_neutral"`

mapray.TonemapMode.ACES — ACES フィルミックの近似。中間調が締まり、明るい部分はなだらかに白へ移ります
mapray.TonemapMode.EXPONENTIAL — 指数関数による単純な圧縮。ONEIL_CLASSIC プリセットの発色です
mapray.TonemapMode.PBR_NEUTRAL — Khronos PBR Neutral。画面に収まる色をほとんど変えません

組み込みの大気プリセットは ACES で露出を合わせてあります。他の種類にすると、プリセットの明るさと見た目がずれます。Atmosphere.applyPreset() もトーンマップを書き込みます。どちらも後から書いた方が残ります。

setTonemapExposure — 露出の倍率¶

トーンマップの前に掛ける露出の倍率です。実際の露出は、この値と大気の露出 (Atmosphere) の積です。

0.5	1.0	2.0

setApplyGamma — 出力ガンマ¶

true で、表示用のガンマ (sRGB) を掛けて出力します。false にすると線形のまま出力するので、暗く見えます。出力を別の処理へ渡すとき以外は true のままにしてください。

true	false

ブルーム¶

明るい部分のまわりに光をにじませます。大気の品質 low / minimal では効きません。

setBloomIntensity — 強さ¶

0 にするとブルームの処理自体を省きます。

0	0.02	0.2

setBloomThreshold — にじみ始める輝度¶

これより明るい部分がにじみの元になります。露出を掛ける前のシーン輝度で指定します。下の図は強さ 0.2 で比べています。

0.1	2.0

setBloomRadius / setBloomSoftKnee — 広がりと立ち上がり¶

setBloomRadius — にじみの広がり
setBloomSoftKnee — しきい値付近の立ち上がりの柔らかさ

半径 0.3	半径 3.0

setBloomMode — 広がり方¶

モード	動作
`"compact"`	明るい点のまわりにだけ小さな暈が付きます。軽い処理です
`"wide"`	画面の広い範囲へ薄く裾を引きます。逆光や夜景が華やかになる代わりに、描画が重くなります。負荷は場面で大きく変わり、地形だけの場面ではほとんど増えませんが、水面が画面を埋める場面では大きく増えます

`"compact"`	`"wide"`

自動露出¶

画面の平均的な明るさに合わせて露出を時間とともに変えます。夕暮れから夜にかけて、目が暗さに慣れていくような見え方になります。大気の品質 low でも効きます (HDR パイプラインが無いときだけ止まります)。

メソッド	内容
`setAutoExposureEnabled`	自動露出を使うか
`setAutoExposureBias`	露出の補正 [EV]。正の値で明るくなります
`setAutoExposureSpeed`	追従の速さ [1/秒]

自動露出が掛ける倍率には上限と下限があり、暗すぎる場面を昼のように持ち上げることはありません。宇宙視点では画面の暗い部分 (宇宙) を測光から外すので、地球が明るくなりすぎません。

なし (太陽の仰角 −0.5°)	あり	あり + 補正 +1 EV

光芒 (サンシャフト)¶

太陽から放射状に伸びる光の筋です。大気の品質 low / minimal では効きません。

メソッド	内容
`setSunShaftsEnabled`	光芒を描くか
`setSunShaftsIntensity`	強さ。0 にすると処理を省きます
`setSunShaftsDensity`	光の筋の伸び
`setSunShaftsDecay`	減衰。小さいほど早く消えます
`setSunShaftsWeight`	濃さ

なし	あり	強さ 0.05

制限事項

光芒は、描き終えた画面から作る効果です。

太陽が画面の中かその近くにあるときだけ出ます。太陽が隠れているとき、カメラの後ろにあるときは出ません
光を遮るものは画面に描かれたものから求めるので、画面の外の地形による遮りは反映されません
太陽のすぐ近くにある強い輝点、たとえば太陽の真下の水面の照り返しからも、弱い筋が出ることがあります

サンプルコード¶

大気なしの Viewer でも、HDR モードを "on" にするとトーンマップやブルームを使えます。ただし背景色 (background_color) は変えられません。

const viewer = new mapray.Viewer( "mapray-container", {
    // ...
    render_effects: {
        hdr_mode: mapray.RenderEffects.HDRMode.ON,
        tonemap_mode: mapray.TonemapMode.PBR_NEUTRAL,
        bloom_intensity: 0.05,
    },
} );

その他のメソッドや詳細はリファレンスマニュアルを参照してください。