1 /******************************************************************************* 2 * Copyright 2011 See AUTHORS file. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 ******************************************************************************/ 16 17 package com.badlogic.gdx.graphics.g3d; 18 19 import com.badlogic.gdx.graphics.GL20; 20 import com.badlogic.gdx.graphics.Mesh; 21 import com.badlogic.gdx.graphics.VertexAttributes; 22 import com.badlogic.gdx.graphics.g3d.model.MeshPart; 23 import com.badlogic.gdx.graphics.g3d.model.Node; 24 import com.badlogic.gdx.graphics.g3d.utils.ShaderProvider; 25 import com.badlogic.gdx.math.Matrix4; 26 import com.badlogic.gdx.utils.Array; 27 import com.badlogic.gdx.utils.Pool; 28 29 /** A Renderable contains all information about a single render instruction (typically a draw call).</p> 30 * 31 * It defines what (the shape), how (the material) and where (the transform) should be rendered by which shader.</p> 32 * 33 * The shape is defined using the mesh, meshPartOffset, meshPartSize and primitiveType members. This matches the members of the 34 * {@link MeshPart} class. The meshPartOffset is used to specify the offset within the mesh and the meshPartSize is used to 35 * specify the part (in total number of vertices) to render. If the mesh is indexed (which is when {@link Mesh#getNumIndices()} > 36 * 0) then both values are in number of indices within the indices array of the mesh, otherwise they are in number of vertices 37 * within the vertices array of the mesh. Note that some classes might require the mesh to be indexed.</p> 38 * 39 * The {@link #material} and (optional) {@link #environment} values are combined to specify how the shape should look like. 40 * Typically these are used to specify uniform values or other OpenGL state changes. When a value is present in both the 41 * {@link #material} and {@link #environment}, then the value of the {@link #material} will be used.</p> 42 * 43 * Renderables can be rendered directly using a {@link Shader} (in which case the {@link #shader} member is ignored). Though more 44 * typically Renderables are rendered via a {@link ModelBatch}, either directly, or by passing a {@link RenderableProvider} like 45 * {@link ModelInstance} to the RenderBatch.</p> 46 * 47 * A ModelInstance returns all Renderables via its {@link ModelInstance#getRenderables(Array, Pool)} method. In which case the 48 * value of {@link ModelInstance#userData} will be set to the {@link #userData} member. The {@link #userData} member can be used 49 * to pass additional data to the shader. However, in most scenario's it is advised to use the {@link #material} or 50 * {@link #environment} member with custom {@link Attribute}s to pass data to the shader.</p> 51 * 52 * In some cases, (for example for non-hierarchical basic game objects requiring only a single draw call) it is possible to extend 53 * the Renderable class and add additional fields to pass to the shader. While extending the Renderable class can be useful, the 54 * shader should not rely on it. Similar to the {@link #userData} member it is advised to use the {@link #material} and 55 * {@link #environment} members to pass data to the shader.</p> 56 * 57 * When using a ModelBatch to render a Renderable, The Renderable and all its values must not be changed in between the call to 58 * {@link ModelBatch#begin(com.badlogic.gdx.graphics.Camera)} and {@link ModelBatch#end()}. Therefor Renderable instances cannot 59 * be reused for multiple render calls.</p> 60 * 61 * When the {@link #shader} member of the Renderable is set, the {@link ShaderProvider} of the {@link ModelBatch} may decide to 62 * use that shader instead of the default shader. Therefor, to assure the default shader is used, the {@link #shader} member must 63 * be set to null.</p> 64 * @author badlogic, xoppa */ 65 public class Renderable { 66 /** Used to specify the transformations (like translation, scale and rotation) to apply to the shape. In other words: it is used 67 * to transform the vertices from model space into world space. **/ 68 public final Matrix4 worldTransform = new Matrix4(); 69 /** The {@link MeshPart} that contains the shape to render **/ 70 public final MeshPart meshPart = new MeshPart(); 71 /** The {@link Material} to be applied to the shape (part of the mesh), must not be null. 72 * @see #environment **/ 73 public Material material; 74 /** The {@link Environment} to be used to render this Renderable, may be null. When specified it will be combined by the shader 75 * with the {@link #material}. When both the material and environment contain an attribute of the same type, the attribute of 76 * the material will be used. **/ 77 public Environment environment; 78 /** The bone transformations used for skinning, or null if not applicable. When specified and the mesh contains one or more 79 * {@link com.badlogic.gdx.graphics.VertexAttributes.Usage#BoneWeight} vertex attributes, then the BoneWeight index is used as 80 * index in the array. If the array isn't large enough then the identity matrix is used. Each BoneWeight weight is used to 81 * combine multiple bones into a single transformation matrix, which is used to transform the vertex to model space. In other 82 * words: the bone transformation is applied prior to the {@link #worldTransform}. */ 83 public Matrix4 bones[]; 84 /** The {@link Shader} to be used to render this Renderable using a {@link ModelBatch}, may be null. It is not guaranteed that 85 * the shader will be used, the used {@link ShaderProvider} is responsible for actually choosing the correct shader to use. **/ 86 public Shader shader; 87 /** User definable value, may be null. */ 88 public Object userData; 89 set(Renderable renderable)90 public Renderable set (Renderable renderable) { 91 worldTransform.set(renderable.worldTransform); 92 material = renderable.material; 93 meshPart.set(renderable.meshPart); 94 bones = renderable.bones; 95 environment = renderable.environment; 96 shader = renderable.shader; 97 userData = renderable.userData; 98 return this; 99 } 100 } 101