One important aspect in order to improve performance and avoid memory leaks in your application is the disposal of unused library entities.
Whenever you create an instance of a *three.js* type, you allocate a certain amount of memory. However, *three.js* creates for specific objects
like geometries or materials WebGL related entities like buffers or shader programs which are necessary for rendering. It's important to
highlight that these objects are not released automatically. Instead, the application has to use a special API in order to free such resources.
This guide provides a brief overview about how this API is used and what objects are relevant in this context.
</p>
<h2>Geometries</h2>
<p>
A geometry usually represents vertex information defined as a collection of attributes. *three.js* internally creates an object of type [link:https://developer.mozilla.org/en-US/docs/Web/API/WebGLBuffer WebGLBuffer]
for each attribute. These entities are only deleted if you call [page:BufferGeometry.dispose](). If a geometry becomes obsolete in your application,
execute the method to free all related resources.
</p>
<h2>Materials</h2>
<p>
A material defines how objects are rendered. *three.js* uses the information of a material definition in order to construct a shader program for rendering.
Shader programs can only be deleted if the respective material is disposed. For performance reasons, *three.js* tries to reuse existing
shader programs if possible. So a shader program is only deleted if all related materials are disposed. You can indicate the disposal of a material by
executing [page:Material.dispose]().
</p>
<h2>Textures</h2>
<p>
The disposal of a material has no effect on textures. They are handled separately since a single texture can be used by multiple materials at the same time.
Whenever you create an instance of [page:Texture], three.js internally creates an instance of [link:https://developer.mozilla.org/en-US/docs/Web/API/WebGLTexture WebGLTexture].
Similar to buffers, this object can only be deleted by calling [page:Texture.dispose]().
</p>
<h2>Render Targets</h2>
<p>
Objects of type [page:WebGLRenderTarget] not only allocate an instance of [link:https://developer.mozilla.org/en-US/docs/Web/API/WebGLTexture WebGLTexture] but also
[link:https://developer.mozilla.org/en-US/docs/Web/API/WebGLFramebuffer WebGLFramebuffer]s and [link:https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderbuffer WebGLRenderbuffer]s
for realizing custom rendering destinations. These objects are only deallocated by executing [page:WebGLRenderTarget.dispose]().
</p>
<h2>Miscellaneous</h2>
<p>
There are other classes from the examples directory like controls or post processing passes which provide *dispose()* methods in order to remove internal event listeners
or render targets. In general, it's recommended to check the API or documentation of a class and watch for *dispose()*. If present, you should use it when cleaning things up.
This question was asked many times by the community so it's important to clarify this matter. Fact is that *three.js* does not know the lifetime or scope
of user-created entities like geometries or materials. This is the responsibility of the application. For example even if a material is currently not used for rendering,
it might base necessary for the next frame. So if the application decides that a certain object can be deleted, it has to notify the engine via calling the respective
*dispose()* method.
</p>
<h3>Does removing a mesh from the scene also dispose its geometry and material?</h3>
<p>
No, you have to explicitly dispose the geometry and material via *dispose()*. Keep in mind that geometries and materials can be shared among 3D objects like meshes.
</p>
<h3>Does *three.js* provide information about the amount of cached objects?</h3>
<p>
Yes. It's possible to evaluate [page:WebGLRenderer.info], a special property of the renderer with a series of statistical information about the graphics board memory
and the rendering process. Among other things, it tells you have many textures, geometries and shader programs are internally stored. If you notice performance problems
in your application, it's a good idea to debug this property in order to easily identify a memory leak.
</p>
<p>
Internal resources for a texture are only allocated if the image has fully loaded. If you dispose a texture before the image was loaded,
nothing happens. No resources were allocated so there is also no need for clean up.
</p>
<h3>Why happens when you call *dispose()* on a texture but the image is not loaded yet?</h3>
<p>
Internal resources for a texture are only allocated if the image has fully loaded. If you dispose a texture before the image was loaded,
nothing happens. No resources were allocated so there is also no need for clean up.
</p>
<h3>What happens when I call *dispose()* and then use the respective object at a later point?</h3>
<p>
The deleted internal resources will be created again by the engine. So no runtime error will occur but you might notice a negative performance impact for the current frame,
especially when shader programs have to be compiled.
</p>
<h3>How should I manage *three.js* objects in my app? When do I know how to dispose things?</h3>
<p>
In general, there is no definite recommendation for this. It highly depends on the specific use case when calling *dispose()* is appropriate. It's important to highlight that
it's not always necessary to dispose objects all the time. A good example for this is a game which consists of multiple levels. A good place for object disposal is when
switching the level. The app could traverse through the old scene and dispose all obsolete materials, geometries and textures. As mentioned in the previous section, it does not
produce a runtime error if you dispose an object that is actually still in use. The worst thing that can happen is performance drop for a single frame.
</p>
<h2>Examples that demonstrate the usage of dispose()</h2>
<p>
[example:webgl_test_memory WebGL / test / memory]<br/>
[example:webgl_test_memory2 WebGL / test / memory2]<br/>
