1 /* 2 * Copyright (c) 2009-2010 jMonkeyEngine 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are 7 * met: 8 * 9 * * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * * Neither the name of 'jMonkeyEngine' nor the names of its contributors 17 * may be used to endorse or promote products derived from this software 18 * without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 22 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 27 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 28 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 29 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 package com.jme3.renderer; 33 34 import com.jme3.light.LightList; 35 import com.jme3.material.RenderState; 36 import com.jme3.math.ColorRGBA; 37 import com.jme3.math.Matrix4f; 38 import com.jme3.scene.Mesh; 39 import com.jme3.scene.VertexBuffer; 40 import com.jme3.shader.Shader; 41 import com.jme3.shader.Shader.ShaderSource; 42 import com.jme3.texture.FrameBuffer; 43 import com.jme3.texture.Image; 44 import com.jme3.texture.Texture; 45 import java.nio.ByteBuffer; 46 import java.util.EnumSet; 47 48 /** 49 * The <code>Renderer</code> is responsible for taking rendering commands and 50 * executing them on the underlying video hardware. 51 * 52 * @author Kirill Vainer 53 */ 54 public interface Renderer { 55 56 /** 57 * Get the capabilities of the renderer. 58 * @return The capabilities of the renderer. 59 */ 60 public EnumSet<Caps> getCaps(); 61 62 /** 63 * The statistics allow tracking of how data 64 * per frame, such as number of objects rendered, number of triangles, etc. 65 * These are updated when the Renderer's methods are used, make sure 66 * to call {@link Statistics#clearFrame() } at the appropriate time 67 * to get accurate info per frame. 68 */ 69 public Statistics getStatistics(); 70 71 /** 72 * Invalidates the current rendering state. Should be called after 73 * the GL state was changed manually or through an external library. 74 */ 75 public void invalidateState(); 76 77 /** 78 * Clears certain channels of the currently bound framebuffer. 79 * 80 * @param color True if to clear colors (RGBA) 81 * @param depth True if to clear depth/z 82 * @param stencil True if to clear stencil buffer (if available, otherwise 83 * ignored) 84 */ 85 public void clearBuffers(boolean color, boolean depth, boolean stencil); 86 87 /** 88 * Sets the background (aka clear) color. 89 * 90 * @param color The background color to set 91 */ 92 public void setBackgroundColor(ColorRGBA color); 93 94 /** 95 * Applies the given {@link RenderState}, making the necessary 96 * GL calls so that the state is applied. 97 */ 98 public void applyRenderState(RenderState state); 99 100 /** 101 * Set the range of the depth values for objects. All rendered 102 * objects will have their depth clamped to this range. 103 * 104 * @param start The range start 105 * @param end The range end 106 */ 107 public void setDepthRange(float start, float end); 108 109 /** 110 * Called when a new frame has been rendered. 111 */ 112 public void onFrame(); 113 114 /** 115 * Set the world matrix to use. Does nothing if the Renderer is 116 * shader based. 117 * 118 * @param worldMatrix World matrix to use. 119 */ 120 public void setWorldMatrix(Matrix4f worldMatrix); 121 122 /** 123 * Sets the view and projection matrices to use. Does nothing if the Renderer 124 * is shader based. 125 * 126 * @param viewMatrix The view matrix to use. 127 * @param projMatrix The projection matrix to use. 128 */ 129 public void setViewProjectionMatrices(Matrix4f viewMatrix, Matrix4f projMatrix); 130 131 /** 132 * Set the viewport location and resolution on the screen. 133 * 134 * @param x The x coordinate of the viewport 135 * @param y The y coordinate of the viewport 136 * @param width Width of the viewport 137 * @param height Height of the viewport 138 */ 139 public void setViewPort(int x, int y, int width, int height); 140 141 /** 142 * Specifies a clipping rectangle. 143 * For all future rendering commands, no pixels will be allowed 144 * to be rendered outside of the clip rectangle. 145 * 146 * @param x The x coordinate of the clip rect 147 * @param y The y coordinate of the clip rect 148 * @param width Width of the clip rect 149 * @param height Height of the clip rect 150 */ 151 public void setClipRect(int x, int y, int width, int height); 152 153 /** 154 * Clears the clipping rectangle set with 155 * {@link #setClipRect(int, int, int, int) }. 156 */ 157 public void clearClipRect(); 158 159 /** 160 * Set lighting state. 161 * Does nothing if the renderer is shader based. 162 * The lights should be provided in world space. 163 * Specify <code>null</code> to disable lighting. 164 * 165 * @param lights The light list to set. 166 */ 167 public void setLighting(LightList lights); 168 169 /** 170 * Sets the shader to use for rendering. 171 * If the shader has not been uploaded yet, it is compiled 172 * and linked. If it has been uploaded, then the 173 * uniform data is updated and the shader is set. 174 * 175 * @param shader The shader to use for rendering. 176 */ 177 public void setShader(Shader shader); 178 179 /** 180 * Deletes a shader. This method also deletes 181 * the attached shader sources. 182 * 183 * @param shader Shader to delete. 184 */ 185 public void deleteShader(Shader shader); 186 187 /** 188 * Deletes the provided shader source. 189 * 190 * @param source The ShaderSource to delete. 191 */ 192 public void deleteShaderSource(ShaderSource source); 193 194 /** 195 * Copies contents from src to dst, scaling if necessary. 196 */ 197 public void copyFrameBuffer(FrameBuffer src, FrameBuffer dst); 198 199 /** 200 * Copies contents from src to dst, scaling if necessary. 201 * set copyDepth to false to only copy the color buffers. 202 */ 203 public void copyFrameBuffer(FrameBuffer src, FrameBuffer dst, boolean copyDepth); 204 205 /** 206 * Sets the framebuffer that will be drawn to. 207 */ 208 public void setFrameBuffer(FrameBuffer fb); 209 210 /** 211 * Set the framebuffer that will be set instead of the main framebuffer 212 * when a call to setFrameBuffer(null) is made. 213 * 214 * @param fb 215 */ 216 public void setMainFrameBufferOverride(FrameBuffer fb); 217 218 /** 219 * Reads the pixels currently stored in the specified framebuffer 220 * into the given ByteBuffer object. 221 * Only color pixels are transferred, the format is BGRA with 8 bits 222 * per component. The given byte buffer should have at least 223 * fb.getWidth() * fb.getHeight() * 4 bytes remaining. 224 * 225 * @param fb The framebuffer to read from 226 * @param byteBuf The bytebuffer to transfer color data to 227 */ 228 public void readFrameBuffer(FrameBuffer fb, ByteBuffer byteBuf); 229 230 /** 231 * Deletes a framebuffer and all attached renderbuffers 232 */ 233 public void deleteFrameBuffer(FrameBuffer fb); 234 235 /** 236 * Sets the texture to use for the given texture unit. 237 */ 238 public void setTexture(int unit, Texture tex); 239 240 /** 241 * Deletes a texture from the GPU. 242 */ 243 public void deleteImage(Image image); 244 245 /** 246 * Uploads a vertex buffer to the GPU. 247 * 248 * @param vb The vertex buffer to upload 249 */ 250 public void updateBufferData(VertexBuffer vb); 251 252 /** 253 * Deletes a vertex buffer from the GPU. 254 * @param vb The vertex buffer to delete 255 */ 256 public void deleteBuffer(VertexBuffer vb); 257 258 /** 259 * Renders <code>count</code> meshes, with the geometry data supplied. 260 * The shader which is currently set with <code>setShader</code> is 261 * responsible for transforming the input verticies into clip space 262 * and shading it based on the given vertex attributes. 263 * The int variable gl_InstanceID can be used to access the current 264 * instance of the mesh being rendered inside the vertex shader. 265 * 266 * @param mesh The mesh to render 267 * @param lod The LOD level to use, see {@link Mesh#setLodLevels(com.jme3.scene.VertexBuffer[]) }. 268 * @param count Number of mesh instances to render 269 */ 270 public void renderMesh(Mesh mesh, int lod, int count); 271 272 /** 273 * Resets all previously used {@link GLObject}s on this Renderer. 274 * The state of the GLObjects is reset in such way, that using 275 * them again will cause the renderer to reupload them. 276 * Call this method when you know the GL context is going to shutdown. 277 * 278 * @see GLObject#resetObject() 279 */ 280 public void resetGLObjects(); 281 282 /** 283 * Deletes all previously used {@link GLObject}s on this Renderer, and 284 * then resets the GLObjects. 285 * 286 * @see #resetGLObjects() 287 * @see GLObject#deleteObject(com.jme3.renderer.Renderer) 288 */ 289 public void cleanup(); 290 291 /** 292 * Sets the alpha to coverage state. 293 * <p> 294 * When alpha coverage and multi-sampling is enabled, 295 * each pixel will contain alpha coverage in all 296 * of its subsamples, which is then combined when 297 * other future alpha-blended objects are rendered. 298 * </p> 299 * <p> 300 * Alpha-to-coverage is useful for rendering transparent objects 301 * without having to worry about sorting them. 302 * </p> 303 */ 304 public void setAlphaToCoverage(boolean value); 305 } 306
