# [name]

アプリケーションのパフォーマンスを向上させ、メモリリークを回避するための重要なこととして、 未使用のライブラリエンティティの廃棄が挙げられます。 three.js型のインスタンスを作成すると、決まった量のメモリが割り当てられます。 しかし、*three.js*はジオメトリやマテリアルのような特定のオブジェクトのために、レンダリングに必要なバッファやshaderといったWebGL関連のエンティティを作成します。これらのオブジェクトは自動的に解放されるわけではありません。 その代わり、アプリケーションはこのようなリソースを解放するために特別なAPIを使用する必要があります。 このガイドでは、このAPIがどのように使用されるのか、また、このコンテキストではどのようなオブジェクトが関連しているのかについて簡単に説明します。

## Geometries

ジオメトリは普通は、属性の集合として定義された頂点の情報を表します。 *three.js*は、内部にはそれぞれの属性に対して、[link:https://developer.mozilla.org/en-US/docs/Web/API/WebGLBuffer WebGLBuffer]型のオブジェクトを作成します。 これらのentityは[page:BufferGeometry.dispose]()が呼ばれた時にのみ削除されます。 もしアプリケーションの中で、あるジオメトリが使われなくなった場合は、関連したリソースを開放するためにこの方法を実行してください。

## Materials

マテリアルは、オブジェクトをどのように描画するかを定義します。 *three.js*はマテリアルの定義情報をレンダリング用のシェーダプログラムを構築するために使います。 シェーダプログラムは対応するマテリアルを捨てることでのみ、削除することができます。 パフォーマンスのために、*three.js*は可能であればすでに存在するシェーダプログラムを再利用しようとします。 そのため、シェーダプログラムは、関連したマテリアルがすべて廃棄された場合のみ削除されます。 [page:Material.dispose]()を実行することで、マテリアルの削除を指示できます。

## Textures

マテリアルの廃棄をしても、テクスチャには影響がありません。 一つのテクスチャが複数のマテリアルに同時に使用されることがあるので、 テクスチャとマテリアルは別々に制御されています。 テクスチャのインスタンスを作成すると、three.jsは内部に[link:https://developer.mozilla.org/en-US/docs/Web/API/WebGLTexture WebGLTexture]を作成します。 バッファと同様に、このオブジェクトは[page:Texture.dispose]()を呼ぶことでしか削除できません。

If you use an *ImageBitmap* as the texture's data source, you have to call [link:https://developer.mozilla.org/en-US/docs/Web/API/ImageBitmap/close ImageBitmap.close]() at the application level to dispose of all CPU-side resources. An automated call of *ImageBitmap.close()* in [page:Texture.dispose]() is not possible, since the image bitmap becomes unusable, and the engine has no way of knowing if the image bitmap is used elsewhere.

## Render Targets

[page:WebGLRenderTarget]型のオブジェクトは、描画先をカスタム出来るように、 [link:https://developer.mozilla.org/en-US/docs/Web/API/WebGLTexture WebGLTexture]インスタンスだけでなく、[link:https://developer.mozilla.org/en-US/docs/Web/API/WebGLFramebuffer WebGLFramebuffer]と [link:https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderbuffer WebGLRenderbuffer]も確保します。 これらのオブジェクトは[page:WebGLRenderTarget.dispose]()を実行することで、解放されます。

## Miscellaneous

exampleディレクトリには、コントロールや後処理用のパスクラスといったクラスがあります。 これらのクラスは内部のイベントリスナーや描画対象を取り除くための*dispose()*メソッドを提供します。 一般的には、APIやクラスのドキュメントで*dispose()*があるかどうか探すのがおすすめです。 *dispose()*メソッドが存在するなら、片付けの際に使うとよいでしょう。

## FAQ

### なぜthree.jsは自動的にオブジェクトを処分できないのですか？

この質問はコミュニティで何度も訊かれた質問なので、この問題についてはきちんと解説します。 実のところ、*three.js*はライフタイムや、ユーザが作成したジオメトリやマテリアルのようなエンティティのスコープの情報をもっていません。これはアプリケーション側に責任があります。例えば、マテリアルが今のところレンダリングのために使用されていなくとも、次のフレームでは必要になるかもしれません。そのため、アプリケーションが特定のオブジェクトを削除しても良いと判断した場合、対応する*dispose()*メソッドを呼ぶことで描画エンジンに対してそのことを知らせなくてはなりません。

### シーンからmeshを取り除くとそのジオメトリとマテリアルも削除されますか？

いいえ。ジオメトリとマテリアルは*dispose()*で明示的に削除する必要があります。 メッシュのような3Dオブジェクト間でジオメトリとマテリアルは共有できることを覚えておいてください。

### *three.js*でキャッシュされたオブジェクトの量について情報を知ることができますか？

はい。グラフィックボードのメモリとレンダリングプロセスの一連の統計情報で レンダラの特別なプロパティである[page:WebGLRenderer.info]を評価することができます。 また、ほかにはテクスチャやジオメトリ、シェーダプログラムがどれくらい内部に保存されているかを知ることができます。 もし、アプリケーションにパフォーマンス上の問題があることに気づいた場合、簡単にメモリリークを見つけるために このプロパティを調べてみることをおすすめします。

### 画像がまだロードされていない時に、テクスチャの*dispose()*を呼び出すとどうなりますか？

テクスチャの内部リソースは、イメージが完全に読み込まれた場合にのみ割り当てられます。 画像が読み込まれる前にテクスチャを破棄しても何も起こりません。 リソースが割り当てられていないので、クリーンアップの必要もありません。

### dispose()を呼び出した後に、対象のオブジェクトを使用すると何が起きますか？

削除された内部のリソースは、エンジンによって再び作成されます。 そのため、ランタイムエラーは発生しませんが、シェーダプログラムのコンパイルが必要な場合には特に 現在のフレームでのパフォーマンスの低下が発生するかもしれません。

### *three.js*のオブジェクトをどのように管理するべきでしょうか？いつオブジェクトを削除するべきでしょうか?

この問いに対する明確で一般的な答えはありません。いつ*dispose()*を呼ぶのが正しいのかは、ユースケースに大きく依存します。常にオブジェクトを削除する必要があるわけではないことは強調しておきます。そのよい例として、複数のレベルで構成されているゲームがあります。こういったアプリの場合、オブジェクトを削除するのに適しているのはレベルを切り替えるときです。 そうすることで、古いシーンを通じてオブジェクトに対して処理を適用し、古いマテリアルやジオメトリ、テクスチャを削除できます。前の章で言及したように、まだ使用中のオブジェクトを削除してもランタイムエラーは発生しません。最悪でも１フレーム分のパフォーマンス低下が発生するだけです。

## Examples that demonstrate the usage of dispose()

[example:webgl_test_memory WebGL / test / memory]
[example:webgl_test_memory2 WebGL / test / memory2]