threejs-core-renderer

threejs-core-renderer

クイックリファレンス

標準的な初期化パターン

import {
  WebGLRenderer, SRGBColorSpace, ACESFilmicToneMapping,
  PCFSoftShadowMap, PerspectiveCamera, Scene
} from 'three';

const renderer = new WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
renderer.outputColorSpace = SRGBColorSpace;
renderer.toneMapping = ACESFilmicToneMapping;
renderer.toneMappingExposure = 1.0;
renderer.shadowMap.enabled = true;
renderer.shadowMap.type = PCFSoftShadowMap;
document.body.appendChild(renderer.domElement);

const scene = new Scene();
const camera = new PerspectiveCamera(50, window.innerWidth / window.innerHeight, 0.1, 1000);

renderer.setAnimationLoop((time) => {
  renderer.render(scene, camera);
});

コンストラクターのパラメーター

パラメーター	型	デフォルト	説明
canvas	HTMLCanvasElement	new canvas	既存のキャンバス要素
context	WebGLRenderingContext	new context	既存の WebGL コンテキスト
precision	'highp' | 'mediump' | 'lowp'	'highp'	シェーダーの精度
alpha	boolean	false	キャンバス背景を透明にするかどうか
premultipliedAlpha	boolean	true	プリマルチプライドアルファブレンディング
antialias	boolean	false	MSAA アンチエイリアシング
stencil	boolean	true	ステンシルバッファー
preserveDrawingBuffer	boolean	false	スクリーンショットに必要
powerPreference	'high-performance' | 'low-power' | 'default'	'default'	GPU 選択のヒント
failIfMajorPerformanceCaveat	boolean	false	ソフトウェアレンダラーの場合に失敗させる
depth	boolean	true	深度バッファー
logarithmicDepthBuffer	boolean	false	大規模なシーンの Z ファイティングを修正

絶対に コンストラクターの実行後に antialias を変更しないでください。作成後は変更できません。

主なプロパティ

プロパティ	型	デフォルト	説明
domElement	HTMLCanvasElement	--	キャンバスです。必ず DOM に追加してください
shadowMap.enabled	boolean	false	影を使う場合は必ず true に設定してください
shadowMap.type	ShadowMapType	PCFShadowMap	シャドウフィルタリングのアルゴリズム
toneMapping	ToneMapping	NoToneMapping	HDR トーンマッピングのアルゴリズム
toneMappingExposure	number	1	トーンマッピングの露出
outputColorSpace	string	SRGBColorSpace	出力の色空間
autoClear	boolean	true	各レンダー呼び出しの前にクリアするかどうか
sortObjects	boolean	true	描画順を自動的に並べ替えるかどうか
clippingPlanes	Plane[]	[]	グローバルクリッピングプレーン
localClippingEnabled	boolean	false	マテリアルごとのクリッピングを有効にするかどうか
info	object	--	レンダリング統計（呼び出し回数、三角形数、メモリ）

重要な警告

ピクセル比の上限設定を絶対に忘れないでください。3x 以上の画面で devicePixelRatio に上限を設けないと、ピクセル負荷が 9 倍以上になります。必ず Math.min(window.devicePixelRatio, 2) を使用してください。

最初のレンダリング後に shadowMap.type を絶対に変更しないでください。シェーダー全体の再コンパイルが発生します。必ず初期化時に一度だけ設定してください。

本番環境のレンダリングループで preserveDrawingBuffer: true を絶対に使用しないでください。バッファースワップの最適化が無効になります。スクリーンショットが必要な場合にのみ有効にしてください。

カメラの near: 0 は絶対に設定しないでください。あらゆる場所で Z ファイティングが発生します。必ず far / near の比率を 10,000 未満に保ってください。

fov、aspect、near、far、または zoom を変更した後に、camera.updateProjectionMatrix() を呼び出すのを絶対に忘れないでください。投影行列は自動更新されません。

Three.js r160 以降で、生の requestAnimationFrame を絶対に使用しないでください。WebXR セッションを自動的に処理する renderer.setAnimationLoop() を必ず使用してください。

クリーンアップ時に renderer.dispose() を呼び出すのを絶対に忘れないでください。呼び出さないと、WebGL コンテキスト、プログラム、テクスチャ、フレームバッファーがリークします。

---

色管理

Three.js r160 以降では、出力時に自動で sRGB 変換を行うリニアワークフローを使用します。

色空間のルール

テクスチャの種類	colorSpace	例
カラー／アルベド	SRGBColorSpace	ディフューズマップ、エミッシブマップ
データ	LinearSRGBColorSpace	法線マップ、ラフネス、メタルネス、AO、ディスプレイスメント

ルール： カラーテクスチャは必ず SRGBColorSpace に設定してください。データテクスチャは必ず LinearSRGBColorSpace に設定してください。これらを取り違えると、白っぽくなったり、彩度が高くなりすぎたりするレンダリング結果になります。

トーンマッピングの選択フローチャート

定数	使用する場面
NoToneMapping	非写実的レンダリング、UI オーバーレイ、アンリットシーン
LinearToneMapping	色変換を最小限に抑えた、基本的な HDR のクランプ
ReinhardToneMapping	汎用用途。色相を良好に保ちます
CineonToneMapping	映画フィルムのようなルック
ACESFilmicToneMapping	PBR のデフォルトの選択肢です。 業界標準のフィルム調カーブ
AgXToneMapping	彩度の高い色では ACES より優れています。明るい青や赤での ACES の色相シフトを回避します。（r160 以降）
NeutralToneMapping	色の正確さを最優先する場合。芸術的な変換を最小限に抑えます

PBR ワークフローでは、必ず ACESFilmicToneMapping または AgXToneMapping を使用してください。彩度の高い色を正確に保つ必要がある場合は、AgXToneMapping を推奨します。

---

シャドウマップの設定

import { PCFSoftShadowMap } from 'three';

renderer.shadowMap.enabled = true;
renderer.shadowMap.type = PCFSoftShadowMap;

種類	品質	パフォーマンス	備考
BasicShadowMap	低（エッジが硬い）	最速	フィルタリングなし
PCFShadowMap	中	中	デフォルト。パーセンテージ・クローサー・フィルタリング
PCFSoftShadowMap	高（エッジが柔らかい）	低速	バイリニア PCF。最も一般的な選択肢
VSMShadowMap	高（非常に柔らかい）	最も低速	ライトブリーディングのアーティファクトが発生することがあります

---

レンダーループとリサイズ

setAnimationLoop（推奨）

renderer.setAnimationLoop((time) => {
  // time is DOMHighResTimeStamp in milliseconds
  renderer.render(scene, camera);
});

// Stop the loop
renderer.setAnimationLoop(null);

ウィンドウのリサイズハンドラー

window.addEventListener('resize', () => {
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix();
  renderer.setSize(window.innerWidth, window.innerHeight);
});

setSize() の前に、必ず camera.aspect を更新し、updateProjectionMatrix() を呼び出してください。

---

カメラシステム

PerspectiveCamera

import { PerspectiveCamera } from 'three';

const camera = new PerspectiveCamera(
  50,                                        // fov (vertical, degrees)
  window.innerWidth / window.innerHeight,    // aspect ratio
  0.1,                                       // near
  1000                                       // far
);
camera.position.set(0, 5, 10);
camera.lookAt(0, 0, 0);

fov、aspect、near、far、または zoom を変更した後は、必ず camera.updateProjectionMatrix() を呼び出してください。

OrthographicCamera

import { OrthographicCamera } from 'three';

const frustumSize = 10;
const aspect = window.innerWidth / window.innerHeight;
const camera = new OrthographicCamera(
  -frustumSize * aspect / 2,   // left
   frustumSize * aspect / 2,   // right
   frustumSize / 2,            // top
  -frustumSize / 2,            // bottom
  0.1, 1000
);

リサイズ時は、必ず視錐台の 6 つのパラメーター（left、right、top、bottom、near、far）をすべて更新し、その後 updateProjectionMatrix() を呼び出してください。

ArrayCamera

1 回の render() 呼び出しで複数のビューポートをレンダリングします。各サブカメラには camera.viewport = new Vector4(x, y, width, height) を設定します。分割画面や VR ステレオに使用します。

CubeCamera

シーンを 6 方向から WebGLCubeRenderTarget にレンダリングします。動的な環境マップに使用します。静的な環境では、cubeCamera.update() を毎フレーム呼び出してはいけません。呼び出すたびにシーンを 6 回レンダリングします。

---

レンダーターゲット

import { WebGLRenderTarget } from 'three';

const renderTarget = new WebGLRenderTarget(1024, 1024);
renderer.setRenderTarget(renderTarget);
renderer.render(scene, camera);
renderer.setRenderTarget(null); // restore default framebuffer
// renderTarget.texture is now usable as a regular Texture

不要になったレンダーターゲットでは、必ず renderTarget.dispose() を呼び出してください。

---

シェーダーのコンパイル

// Synchronous -- blocks the thread
renderer.compile(scene, camera);

// Asynchronous -- non-blocking, prevents frame drops (r160+)
await renderer.compileAsync(scene, camera);

ジャストインタイムのシェーダーコンパイルによるカクつきを防ぐため、アセットの読み込み後、最初の表示レンダリングの前に必ず compileAsync() を呼び出してください。

---

ビューポートとシザー

// Render to a sub-region of the canvas
renderer.setViewport(x, y, width, height);
renderer.setScissor(x, y, width, height);
renderer.setScissorTest(true);
renderer.render(scene, camera);

// Reset to full canvas
renderer.setScissorTest(false);
renderer.setViewport(0, 0, canvas.width, canvas.height);

---

クリッピング平面

import { Plane, Vector3 } from 'three';

// Global clipping (affects all objects)
renderer.clippingPlanes = [new Plane(new Vector3(0, -1, 0), 1)];

// Per-material clipping (MUST enable localClippingEnabled)
renderer.localClippingEnabled = true;
material.clippingPlanes = [plane];
material.clipIntersection = false; // false = union, true = intersection
material.clipShadows = true;       // also clip shadow geometry

---

クリーンアップと破棄

renderer.setAnimationLoop(null);
renderer.dispose();
renderer.domElement.remove();

レンダラーを削除するときは、必ず dispose() を呼び出してください。これにより、WebGL コンテキスト、コンパイル済みのシェーダープログラム、テクスチャ、フレームバッファーがすべて解放されます。

---

WebGPU レンダラー

Three.js には、TSL（Three Shading Language）のノードベースマテリアルを使用する実験的な WebGPURenderer が含まれています。WebGPU 固有のガイダンスについては、threejs-impl-webgpu スキルを参照してください。

---

参考リンク

• references/methods.md -- WebGLRenderer と Camera の API シグネチャーの完全な一覧
• references/examples.md -- 動作するコード例
• references/anti-patterns.md -- やってはいけないこと

公式情報源

• https://threejs.org/docs/#api/en/renderers/WebGLRenderer
• https://threejs.org/docs/#api/en/cameras/PerspectiveCamera
• https://threejs.org/docs/#api/en/cameras/OrthographicCamera
• https://threejs.org/docs/#api/en/renderers/WebGLRenderTarget