A Renderable contains all information about a single render instruction (typically a draw call).

It defines what (the shape), how (the material) and where (the transform) should be rendered by which shader.

The shape is defined using the mesh, meshPartOffset, meshPartSize and primitiveType members. This matches the members of the MeshPart class. The meshPartOffset is used to specify the offset within the mesh and the meshPartSize is used to specify the part (in total number of vertices) to render. If the mesh is indexed (which is when Mesh#getNumIndices() > 0) then both values are in number of indices within the indices array of the mesh, otherwise they are in number of vertices within the vertices array of the mesh. Note that some classes might require the mesh to be indexed.

The material and (optional) environment values are combined to specify how the shape should look like. Typically these are used to specify uniform values or other OpenGL state changes. When a value is present in both the material and environment, then the value of the material will be used.

Renderables can be rendered directly using a Shader (in which case the shader member is ignored). Though more typically Renderables are rendered via a ModelBatch, either directly, or by passing a RenderableProvider like ModelInstance to the RenderBatch.

A ModelInstance returns all Renderables via its ModelInstance#getRenderables(Array, Pool) method. In which case the value of ModelInstance#userData will be set to the userData member. The userData member can be used to pass additional data to the shader. However, in most scenario's it is advised to use the material or environment member with custom Attributes to pass data to the shader.

In some cases, (for example for non-hierarchical basic game objects requiring only a single draw call) it is possible to extend the Renderable class and add additional fields to pass to the shader. While extending the Renderable class can be useful, the shader should not rely on it. Similar to the userData member it is advised to use the material and environment members to pass data to the shader.

When using a ModelBatch to render a Renderable, The Renderable and all its values must not be changed in between the call to ModelBatch#begin(com.badlogic.gdx.graphics.Camera) and ModelBatch#end(). Therefor Renderable instances cannot be reused for multiple render calls.

When the shader member of the Renderable is set, the ShaderProvider of the ModelBatch may decide to use that shader instead of the default shader. Therefor, to assure the default shader is used, the shader member must be set to null.